> ## Documentation Index > Fetch the complete documentation index at: https://docs-staging.blumint.com/llms.txt > Use this file to discover all available pages before exploring further. # Registers your player lookup callback URL. > Registers the https URL BluMint calls to get your player id for a BluMint user from an account they linked. BluMint calls it only for a game whose player ids it gets from this URL, rather than identifying players by an account they linked themselves: when the user registers for one of your game's tournaments, and again before every create, once for each player in the match, so each create carries the id you answered then. BluMint never calls it for a spectator, and never for a player who has linked none of the accounts you chose in the setup form: it asks that player to link one instead. Register this URL before your game's first tournament opens: a player can register for one of your game's tournaments only after your lookup finds them, so until this URL is registered no one can. BluMint stops waiting after 3 seconds for a lookup made when a player registers, and after 10 seconds for each try before a create. Use and keep the ids BluMint sends and the player ids you answer only to put players into matches in your game's BluMint tournaments and to let the spectators who chose to watch do so. Share them with no one else, and keep them secure. Registering again replaces the previous URL. The URL's host must resolve only to public addresses, an IP-address host must be a public IPv4 address, and BluMint follows no redirects, so the URL must answer directly. Which answer to send when BluMint calls your URL: | Situation | Status | What happens next | | --- | --- | --- | | You know the player | `200` | At registration, the player can register. Before a create, the create identifies the player by the id you answered. | | You don't know the player | `200` | At registration, the player is asked to connect their account in your game, then check again. Before a create, BluMint asks the player to connect their account and retries under the same key every 60 seconds. A player still unlinked when the tournament's hold length runs out is disqualified. | | You are down or overloaded | `502`, `503`, `504`, `408`, `429`, or no answer | At registration, the player is told you aren't responding and to try again in a minute. Before a create, BluMint tries the create again under the same key, as it does when your create URL is down, then the host takes the match and starts it manually. | | BluMint's request breaks the rules in this guide | `400` | At registration, the player can't register. Before a create, the host takes the match and starts it manually. | | Your server failed on this request | `500` | At registration, the player is told you aren't responding and to try again in a minute. Before a create, the host takes the match and starts it manually. | For what BluMint sends to your URL and how to answer it, see [Player lookup](/guide/player-lookup). ## OpenAPI ````yaml /openapi.json post /tournaments/setLookupPlayer openapi: 3.0.1 info: title: BluMint game partner API version: 2.0.0 description: >- Reference for the endpoints your game uses to run BluMint tournaments. For the walkthrough, see the [game integration guide](https://docs.blumint.com). To request an API key, fill in the [game partner setup form](https://staging.blumint.io/contact/game-partner), and for a question, [contact BluMint](https://staging.blumint.io/contact). license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html servers: - description: Staging, for building and testing url: https://staging.blumint.io/api - description: Production url: https://app.blumint.com/api security: - ApiKeyAuth: [] tags: [] paths: /tournaments/setLookupPlayer: post: tags: - Tournaments summary: Registers your player lookup callback URL. description: >- Registers the https URL BluMint calls to get your player id for a BluMint user from an account they linked. BluMint calls it only for a game whose player ids it gets from this URL, rather than identifying players by an account they linked themselves: when the user registers for one of your game's tournaments, and again before every create, once for each player in the match, so each create carries the id you answered then. BluMint never calls it for a spectator, and never for a player who has linked none of the accounts you chose in the setup form: it asks that player to link one instead. Register this URL before your game's first tournament opens: a player can register for one of your game's tournaments only after your lookup finds them, so until this URL is registered no one can. BluMint stops waiting after 3 seconds for a lookup made when a player registers, and after 10 seconds for each try before a create. Use and keep the ids BluMint sends and the player ids you answer only to put players into matches in your game's BluMint tournaments and to let the spectators who chose to watch do so. Share them with no one else, and keep them secure. Registering again replaces the previous URL. The URL's host must resolve only to public addresses, an IP-address host must be a public IPv4 address, and BluMint follows no redirects, so the URL must answer directly. Which answer to send when BluMint calls your URL: | Situation | Status | What happens next | | --- | --- | --- | | You know the player | `200` | At registration, the player can register. Before a create, the create identifies the player by the id you answered. | | You don't know the player | `200` | At registration, the player is asked to connect their account in your game, then check again. Before a create, BluMint asks the player to connect their account and retries under the same key every 60 seconds. A player still unlinked when the tournament's hold length runs out is disqualified. | | You are down or overloaded | `502`, `503`, `504`, `408`, `429`, or no answer | At registration, the player is told you aren't responding and to try again in a minute. Before a create, BluMint tries the create again under the same key, as it does when your create URL is down, then the host takes the match and starts it manually. | | BluMint's request breaks the rules in this guide | `400` | At registration, the player can't register. Before a create, the host takes the match and starts it manually. | | Your server failed on this request | `500` | At registration, the player is told you aren't responding and to try again in a minute. Before a create, the host takes the match and starts it manually. | For what BluMint sends to your URL and how to answer it, see [Player lookup](/guide/player-lookup). operationId: setLookupPlayer requestBody: required: true content: application/json: schema: type: object required: - lookupPlayerUrl properties: lookupPlayerUrl: type: string format: uri description: The https URL of your player lookup endpoint. example: https://www.yourgame.com/api/player/lookup authentication: description: >- The secret BluMint sends when it calls your lookup endpoint. When omitted, any secret registered earlier stays in place. allOf: - $ref: '#/components/schemas/CallbackAuthentication' responses: '200': description: The lookup callback URL is registered. content: application/json: schema: type: object required: - message properties: message: type: string example: Success - Player lookup callback URL set successfully. '400': $ref: '#/components/responses/CallbackRegistrationRefused' '401': $ref: '#/components/responses/CallbackRegistrationUnauthenticated' '404': $ref: '#/components/responses/CallbackRegistrationGameNotFound' '405': $ref: '#/components/responses/CallbackRegistrationMethodNotAllowed' callbacks: lookupPlayer: '{$request.body#/lookupPlayerUrl}': post: description: |- Answer quickly. BluMint stops waiting after 3 seconds for a lookup sent while a player registers, and sends it only once. Before a create, BluMint waits up to 10 seconds for each lookup. A timeout counts as no answer, the outage row of the decision table above. BluMint reads only the status of a failed lookup, so the body of a 400 or 500 can be anything. Any other answer counts like the 400 row, a 200 whose body breaks the rules below included, except another 5xx, which counts like the 500 row. When you don't know the player, answer 200 with [] or [null] for that key, or leave the key out. All three mean the same thing. Never answer 404: BluMint counts it like the 400 row. When your server is down only for a while, answer 503 or another status on the outage row. A 400, a 500, or any answer the table does not list is final. BluMint looks up every player of a match just before its create, and sends one create per match of a round at the same moment, so a 256-team single-elimination tournament with one player per team sends about 256 lookups together. BluMint sets no limit on how many it sends at once, so accept the burst rather than answering 429. requestBody: description: >- One BluMint user per call. Each key is an authentication method you chose in the setup form that the user has linked on BluMint and that BluMint looks players up by (today discord, epic, twitch or lichess), and its array holds exactly one id, the user's id on that provider. A user holds at most one account per provider. With your secret in the body, the body also carries that field. required: true content: application/json: schema: type: object additionalProperties: oneOf: - type: array minItems: 1 maxItems: 1 items: type: string description: >- An authentication method key, holding the user's id on that provider. - type: string description: >- Your secret, under the body key you registered, when its location is body. example: discord: - '274220342558756145' responses: '200': description: >- For a player you know, answer each key with a one-entry array holding your player id for that account, a non-empty string of at most 256 printable characters. For a miss, answer [] or [null], or leave the key out. Two keys must never identify different players, and an array never holds more than one entry; either fails the call. Keys BluMint did not send are ignored. A miss is never a 404. content: application/json: schema: type: object additionalProperties: type: array maxItems: 1 items: type: string nullable: true minLength: 1 maxLength: 256 pattern: \S example: discord: - emb1_example method: post type: path path: '{$request.body#/lookupPlayerUrl}' security: - ApiKeyAuth: [] components: schemas: CallbackAuthentication: type: object required: - secret - config properties: secret: type: string description: >- A value you choose, which BluMint sends to your server so you can tell the call came from BluMint. It is not your BluMint API key, so never put that key here. Use a long random value. example: your-inbound-secret config: type: object description: >- Where BluMint puts the secret. It sends valuePrefix, then the secret, then valueSuffix, under the name in key. In a header, that value may hold only tabs and Latin-1 characters from U+0020 through U+00FF other than DEL (U+007F), and cannot start or end with a space or tab, which your server's HTTP parser strips, so trim the newline or space a secret read from a file often ends in. BluMint refuses any other header value with 400. required: - location - key properties: location: type: string enum: - header - queryParam - body description: >- header sends the secret as a request header, and queryParam as a query parameter. body puts it into every POST body BluMint sends this URL as a top-level field: check that field, then remove it before you read or validate the rest of the body, and, on a callback that carries an Idempotency-Key, before you compare a request with an earlier one under the same key. example: header key: type: string description: >- The header name, query parameter or body field that carries the secret. BluMint refuses the registration with 400, quoting the key and saying whether it is a header or a body field, when the key names something it already sends this callback in the same place: a body field such as `teams`, any sign-in method field a player lookup can carry (`discord`, `epic`, `twitch` and `lichess`, even one your game does not use), the `Idempotency-Key` header, or a header every BluMint POST carries (`Accept`, `Accept-Encoding`, `Connection`, `Content-Length`, `Content-Type`, `Host` and `User-Agent`). Header names match in any case, and body fields exactly. A header key must be a valid HTTP header name, one or more letters, digits or characters from `!#$%&'*+-.^_|~` or the backtick, with no spaces, and cannot be `common`, `delete`, `expect`, `get`, `head`, `patch`, `post`, `put`, `trailer`, `transfer-encoding` or `__proto__` in any case, names BluMint's HTTP client reserves. A body key cannot be a built-in JavaScript object property name such as `constructor`, `toString` or `__proto__`. A query parameter key may be any string. A name such as `blumint_secret` passes every rule. example: Authorization valuePrefix: type: string description: Text BluMint sends before the secret, such as "Bearer ". example: 'Bearer ' valueSuffix: type: string description: Text BluMint sends after the secret. responses: CallbackRegistrationRefused: description: >- The URL is missing, is not a valid absolute URL or is not https, contains a user name or password (`user:pass@`), has an IP-address host other than a public IPv4 address, the authentication block is malformed, its header key or value is not a valid HTTP header name or value, its header key is a name BluMint's HTTP client reserves, its body key is a built-in JavaScript object property name, or its key names a header or body field BluMint already sends this callback, which for a lookup is every sign-in method field a lookup can carry. A refusal of the key quotes it and says whether it is a header or a body field. CallbackRegistrationUnauthenticated: description: The X-Api-Key header is missing or unknown. CallbackRegistrationGameNotFound: description: The API key is bound to no game, or its game does not exist. CallbackRegistrationMethodNotAllowed: description: The method is not POST. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Api-Key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.