# Get a contact's position

> The live queue position, how far it is to the front, and how many referrals until the next jump, served straight from Redis so it stays fast even at a million contacts.

Source: https://getlaunchlist.com/help/docs/api/contacts-position

---

Requires the `contacts:read` scope.

Everything you need to render somebody's place in the queue.

| Field       | Meaning                                                             |
| ----------- | ------------------------------------------------------------------- |
| `position`  | Where they are now, including any head start you configured         |
| `to_first`  | How many **more referrals** it would take to reach first place      |
| `next_jump` | How many places **one more referral** would move them up, right now |

All three are `null` when the contact is not on the board, for example a signup the spam guard held
for review. The overflow lock does not affect these values: it withholds a contact's identity, not
their standing, so an over-cap contact still returns a real `position`.

There is a second case worth handling: on a project where a referral is configured to be worth **no
points**, `position` is a real number while `to_first` and `next_jump` are both `null`. Both of
those fields answer "what does one more referral buy", and on that project the honest answer is
nothing, so we return nothing rather than promising a climb that will not happen. Hide the nudge
when they are `null`; do not fall back to 1.

> [!WARNING] `to_first` counts referrals, not places
> It is not the distance to the front of the queue. It is how many people this contact would have
> to refer to out-point whoever is currently first. `0` means they are already there.

## Why this is a separate endpoint

Position is **never stored**. It is read live from the referral leaderboard, so it is correct the
moment you ask rather than correct as of the last recalculation.

The read is `O(log n)`, the same at a million contacts as at a hundred, which is why there is no
nightly job and no drift.

> [!TIP] `next_jump` is the conversion mechanic
> "Refer 1 more person to move up 1,102 places" outperforms "share this link" by a wide margin,
> because it is specific and it is nearly always achievable. It is the single most valuable field
> here. Remember it is a number of places climbed, not a destination rank: add it to nothing.

## Next

- [How referrals work](/help/docs/referrals/how-it-works)
- [Referrals for one contact](/help/docs/api/contacts-referrals)