> ## 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.

# Player lookup

> How BluMint asks your server for your own player id, and what each answer does to a player.

## Player lookup

If BluMint identifies your players by your own player ids, your lookup URL is required. Register it 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 the URL is registered no one can. An integration identifies its players one way only, so once you choose your own player ids, every create identifies every player by the id your lookup answered, never by a linked account. The full lookup schemas are in the [API reference](https://docs-staging.blumint.com/api-reference/introduction.md), in the callbacks of the `setLookupPlayer` endpoint.

BluMint sends one lookup per player. The body has one key for each authentication method you chose in the setup form that the player has linked on BluMint and that BluMint looks players up by (today `discord`, `epic`, `twitch` or `lichess`, with more as BluMint adds them), holding that account's id, plus your secret if you send it in the body. BluMint doesn't call your lookup for a player who has linked none of them, and asks that player to link one instead. It never calls your lookup for a spectator:

```json theme={null}
{
  "discord": ["274220342558756145"]
}
```

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, or `[]` when you don't know the player:

```json theme={null}
{
  "discord": ["emb1_example"]
}
```

If two keys lead to different players of yours, BluMint can't tell which one is playing, so it treats the answer as broken and the lookup fails.

When your lookup doesn't find a player, BluMint links them to the connect page you gave in the setup form, an https page where a player connects the account they linked on BluMint to your game. BluMint asks them to approve that same account there, then check again:

<video autoPlay muted loop playsInline aria-label="A player presses Join on BluMint, the Approve your Discord account for Ember dialog opens with Open Ember and Check again, and Check again registers them" poster="/images/shared/connect-account.png" src="https://mintcdn.com/blumint-staging/PJA2rnJk462wP1gs/images/shared/connect-account.mp4?fit=max&auto=format&n=PJA2rnJk462wP1gs&q=85&s=092c0e766a49f9ea6eb0e0b7479d9d54" />

What your players see on BluMint when your lookup doesn't find them, and their check again once they approve

### Which lookup answer to send when

| 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. |

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, including a `200` whose body breaks the rules above, except another `5xx`, which counts like the `500` row.

* **An unknown 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, so the player can't register and a match being set up goes to the host, instead of the player being asked to approve their account for your game.
* **A brief outage.** While you are briefly down or overloaded, answer `503` or another status on the down-or-overloaded row, never `500` or `400`, which BluMint doesn't retry, so a match being set up goes to the host at once.

### Timing

* When a player registers, BluMint waits 3 seconds for your answer and sends the lookup once, because the player is waiting. Answer in well under that, or the player is told you aren't responding.
* Before each create, BluMint looks up every player in the match again and waits up to 10 seconds for each. It sends each lookup once per try of the create, and a lookup outage makes BluMint try the whole create again, lookups included, as an outage on your create does.

### Bursts

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, and tournaments of your game that start together add to that. BluMint applies no limit on how many it sends at once. Accept that burst rather than answering `429`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.