Skip to content

Use a friend's invitation code

POST
/api/referral/claim
curl --request POST \
--url https://foxleague.ai/api/referral/claim \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "code": "example" }'

Stores the invitation code you arrived with, before you pay for your team. The code is case-insensitive. Nothing is spent or reserved yet: a place is taken only when your paid registration creates your team. Your friend’s places go to the first friends who complete the paid registration, whichever of your friend’s codes they used. A team made without paying (a wallet that already holds enough cards) takes no invitation. A second code replaces the first.

When your paid team is created with the code while your friend still has a free place, it gets welcome_tickets free ranked tickets and your friend starts counting your matches toward a reward. When no place is left then (or the programme closed), your team is registered without it and you get a notification saying why.

Who: a signed-in wallet with no team yet.

Rate limit: at most 10 claims per session wallet in any 60 seconds by default (referral.claim_max_per_window, referral.claim_window_seconds); one more is answered HTTP 429 before anything is read. Claiming the code your open claim already holds again stores nothing new.

Refusals:

  • Too many invitation checks from this wallet. Wait <wait> <unit>, then reload this page. (rate_limited, HTTP 429 with a Retry-After header): this wallet sent more claims than its budget allows. Nothing was read or stored: keep the code and ask again after the wait.
  • Invitations are closed right now. You can still register your team. (programme_off): the programme is switched off.
  • Invitations are paused for now. You can still register your team. (invitations_paused): too few starter cards are free to give new teams their squads.
  • This invitation code does not exist. Check the link or register without it. (unknown_code): no invitation has this code.
  • This is your own invitation. Give it to a friend. (own_code): the code is one of your own invitations.
  • This invitation is no longer valid: your friend has no invitations left. (no_invitation_left): every place of your friend’s team is taken (any code of that team takes a free place, so a code another friend used is no refusal while a place is free).
  • Your team is already registered, so an invitation no longer applies. (already_registered): this wallet already has a team.

Every refusal carries the word in brackets as code. unknown_code, code_used, own_code, no_invitation_left and already_registered are final for that code: asking again with it changes nothing. programme_off, invitations_paused and rate_limited are not: keep the code and ask again later. A failure on our side answers code: "server_error": ask again in a moment.

A body that is not this JSON (a missing code, an unknown field) is answered HTTP 422 with a plain text body.

Media type application/json

The invitation code you arrived with.

object
code
required

The invitation code, as in your friend’s link. Case-insensitive.

string
Example generated
{
"code": "example"
}

Success or a refusal: read success (the refusals are in the description).

Media type application/json
object
code

A machine-readable reason next to error, set only where the caller must act differently. tx_pending: the payment was not refused but could not be verified yet; keep the transaction hash and confirm again with the same hash, never pay twice.

string | null
data

The answer. Present when success is true.

object
inviter_team
required

The team name of the friend who invited you.

string
welcome_tickets
required

The free ranked tickets your paid team gets if this invitation is still free when you pay (referral.welcome_tickets now; 0 = none). Nothing is reserved by the claim.

integer format: int64
error

Why the request was refused, in plain words. Present when success is false.

string | null
success
required

true when the request did what it asked. false is a refusal: read error.

boolean
Example
{
"success": true,
"data": {
"inviter_team": "FC Vultur",
"welcome_tickets": 5
}
}

No valid session. The body is plain text: Missing Authorization header, Invalid Authorization format, Invalid session token or Session expired or invalid. Sign in again.

Media type text/plain
string
Example
Session expired or invalid

See the description.

Media type application/json
object
code

A machine-readable reason next to error, set only where the caller must act differently. tx_pending: the payment was not refused but could not be verified yet; keep the transaction hash and confirm again with the same hash, never pay twice.

string | null
data

The answer. Present when success is true.

object
inviter_team
required

The team name of the friend who invited you.

string
welcome_tickets
required

The free ranked tickets your paid team gets if this invitation is still free when you pay (referral.welcome_tickets now; 0 = none). Nothing is reserved by the claim.

integer format: int64
error

Why the request was refused, in plain words. Present when success is false.

string | null
success
required

true when the request did what it asked. false is a refusal: read error.

boolean
Example generated
{
"code": "example",
"data": {
"inviter_team": "example",
"welcome_tickets": 1
},
"error": "example",
"success": true
}