Referrals

Each user gets their own code lazily (first read creates it). Rewards are paid server-side on claim — both reward_referrer and reward_referee are honored, clamped to any currency max_balance, and logged to currency_transactions under source = 'referral'.

Endpoints

Method	Path	Description
GET	`/client/referrals/my-code`	Get (or lazily create) the caller's referral code.
POST	`/client/referrals/claim`	Claim someone else's code.

GET /client/referrals/my-code

If the user already has a code, returns it. Otherwise a new code is generated (with up to 5 retries on a unique-code collision). Rewards are copied from the first admin-created template code (if one exists).

Response 200 (existing) / 201 (newly created)

{
  "data": {
    "id": "…",
    "app_user_id": "…",
    "code": "X3Q9K2",
    "reward_referrer": {},
    "reward_referee": {},
    "current_uses": 0,
    "max_uses": null,
    "is_active": true,
    "owner_id": "…",
    "uses_count": 0,
    "expires_at": null,
    "created_at": "…"
  }
}

Errors

500 RETRY_EXHAUSTED — could not generate a unique code after 5 attempts.
500 CREATE_FAILED.

Try it:

GET/client/referrals/my-code

client auth

curl -X GET 'https://api.amba.dev/v1/client/referrals/my-code'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET "${BASE_URL}/client/referrals/my-code" \
  -H "X-Api-Key: ${CLIENT_API_KEY}" \
  -H "Authorization: Bearer ${SESSION_TOKEN}"

POST /client/referrals/claim

All validation + the referral_claims insert + the current_uses increment run under FOR UPDATE on the code row so concurrent claims serialize. Reward grants run post-commit as best-effort — a grant failure is logged but the claim succeeds (operators reconcile from currency_transactions).

Request

Field	Type	Required
`code`	string	yes

Response 201

{
  "data": {
    "id": "…",
    "referral_code_id": "…",
    "code_id": "…",
    "referrer_id": "…",
    "referee_id": "…",
    "reward": { "gems": 10 },
    "claimed_at": "…"
  }
}

code_id repeats referral_code_id, and reward is what the code grants the referee. referrer_id is null for a code no user owns.

Errors

400 SELF_REFERRAL — the code belongs to the caller.
400 MAX_USES_REACHED — code hit its use cap.
400 ALREADY_CLAIMED — caller has already claimed this code.
400 ALREADY_REFERRED — caller already claimed another user's code. Each user can be referred by one other user; codes your team creates (with no owning user) don't count toward it.
404 INVALID_CODE — code not found or inactive.
500 CLAIM_FAILED.

Try it:

POST/client/referrals/claim

client auth

curl -X POST 'https://api.amba.dev/v1/client/referrals/claim' \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "INVITE123"
}'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST "${BASE_URL}/client/referrals/claim" \
  -H "X-Api-Key: ${CLIENT_API_KEY}" \
  -H "Authorization: Bearer ${SESSION_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"code":"INVITE123"}'

On this page