Referrals
Individual referral attempts and their lifecycle state
A Referral is one referred person's journey through your campaign: from the first link click, through the qualification gates, to validation and reward. Referrals are created by Invitebase (a link click creates one in clicked); the API exposes read access to their state and gate progress.
The Referral object
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier (a UUID). |
object | string | Always referral. |
status | string | Lifecycle state — see the status table. |
campaign_id | string | The Campaign this referral belongs to. |
referrer_id | string | The Referrer who made the referral. |
referred_user_id | string | Your id for the referred end-user, once known. |
gate_progress | array | Per-condition progress toward the qualification gate (below). |
is_billable | boolean | Whether this referral counts toward billing (true once validated). |
validated_at | string (date-time) | When the referral validated, if it has. |
mode | string | test or live. |
livemode | boolean | Whether the referral exists in live mode. |
created_at | string (date-time) | Creation time (the first click). |
Each gate_progress entry:
| Field | Type | Description |
|---|---|---|
event | string | The event this condition tracks, e.g. subscription_started. |
target | number | The value the condition requires — a count of occurrences, or a summed value/count. |
current | number | Progress so far toward target from matching events. |
satisfied | boolean | Whether the condition has been met (current ≥ target). |
satisfied_at | string (date-time) | When it was met, if it has been. |
Referral statuses
The referral lifecycle is a state machine. Linked ≠ validated: linked means a signup bound to a referrer; validated means the referred user passed the qualification gates and fraud checks. Rewards and billing only ever fire on validated.
| Status | Meaning |
|---|---|
clicked | Someone opened the referral link; no signup yet. |
signed_up | The referred user signed up and was linked to a referrer. |
in_progress | The referred user is working through the qualification gates. |
validated | All gates passed inside the window, fraud checks cleared. Billable; triggers reward creation. |
reward_pending | A Reward has been created and is awaiting fulfillment. |
reward_fulfilled | The reward was delivered (app grant sent or payout completed). Terminal. |
reward_failed | Payout fulfillment failed (money rewards only, e.g. payout error). |
expired | The qualification window passed without the gates being satisfied. Terminal. |
rejected | Rejected by the fraud rules on the pass that would have validated it, or reversed later. Terminal, never billed. |
List referrals
GET/v1/referrals
Returns a paginated list of referrals, filterable by campaign, referrer, and status.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer | No | 1–100, default 25. |
starting_after | query | string | No | Cursor (referral id) for the next page. |
campaign_id | query | string | No | Only referrals in this campaign. |
referrer_id | query | string | No | Only referrals made by this referrer. |
status | query | string | No | Only referrals in this status. |
curl "https://api.invitebase.com/v1/referrals?campaign_id=7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15&status=validated" \
-H "Authorization: Bearer $INVITEBASE_SECRET_KEY"Response — 200 OK:
{
"object": "list",
"has_more": false,
"data": [
{
"id": "2c9d4e7f-1a63-48b5-8e02-6f3a9b1d5c74",
"object": "referral",
"status": "validated",
"campaign_id": "7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15",
"referrer_id": "6b1d4f9a-8e25-4c07-a3f6-1c5e9d7b2a84",
"referred_user_id": "usr_456",
"gate_progress": [
{
"event": "subscription_started",
"target": 1,
"current": 1,
"satisfied": true,
"satisfied_at": "2026-07-08T18:20:00Z"
}
],
"is_billable": true,
"validated_at": "2026-07-08T18:20:05Z",
"mode": "test",
"livemode": false,
"created_at": "2026-07-02T11:40:00Z"
}
]
}Retrieve a referral
GET/v1/referrals/{referralId}
Returns the referral, including gate progress.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
referralId | path | string | Yes | The referral id. |
curl https://api.invitebase.com/v1/referrals/2c9d4e7f-1a63-48b5-8e02-6f3a9b1d5c74 \
-H "Authorization: Bearer $INVITEBASE_SECRET_KEY"Response — 200 OK: the Referral object. Returns 404 if the referral does not exist.
{
"id": "2c9d4e7f-1a63-48b5-8e02-6f3a9b1d5c74",
"object": "referral",
"status": "in_progress",
"campaign_id": "7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15",
"referrer_id": "6b1d4f9a-8e25-4c07-a3f6-1c5e9d7b2a84",
"referred_user_id": "usr_456",
"gate_progress": [
{
"event": "subscription_started",
"target": 1,
"current": 0,
"satisfied": false
}
],
"is_billable": false,
"mode": "test",
"livemode": false,
"created_at": "2026-07-02T11:40:00Z"
}