---
title: "Claim a referral code"
method: POST
path: "/referral/claim/"
tags: ["referral"]
---

# Claim a referral code

`POST /referral/claim/`

## Request

- Base URL: `https://api.getoneprofile.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.getoneprofile.ai/referral/claim/`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Attribute the caller's workspace to a referral code and pay the signup rewards. Safe to call repeatedly and never an error: a code that does not apply reports `attributed: false`. Requires a signed-in user rather than an API key: the claim records who signed up, and an API key has no person behind it.

## Request body

- ReferralClaimRequestSchema: A referral code captured from the URL, offered up by a newly signed-up user.
  - `code` string, required: The referral code as captured. Trimmed and normalized server-side.
  - `source` string, nullable: The affiliate's own tag for where the link was shared, banked at click time by the link redirect. Absent for a link followed any other way. Narrowed rather than validated server-side: an unrecognized value becomes untagged rather than failing a claim.

## Response `200`

Successful Response

- ReferralClaimReadSchema: The outcome of a claim. Always 200. A code that does not apply (a reload, an existing customer clicking a colleague's link) reports ``attributed: false`` rather than an error, because none of those are failures worth alarming a new user about.
  - `attributed` boolean, required: Whether the code was recorded against this workspace.
  - `credits_on_upgrade` integer, required: Whole credits this workspace will receive when it starts a paid plan; 0 when nothing was attributed. Signing up pays nothing, so this is the promise the welcome message makes.
  - `referrer_name` string, nullable, required: The workspace that invited them, for the welcome message.

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `422`: Invalid request made to the API.
- `500`: Internal server error.
- `502`: Bad gateway error.
- `503`: Service unavailable.

---

[API](https://skmtc.dev/getoneprofile/apis/api-reference-oneprofile.md) · [All operations](https://skmtc.dev/getoneprofile/apis/api-reference-oneprofile/llms.txt) · [OpenAPI document](https://skmtc.dev/getoneprofile/apis/api-reference-oneprofile/revisions/4a6bd71e3f02?raw)