Referrals
REST API reference for referrals
This reference is generated from the Invitebase OpenAPI contract.
Individual referral attempts and their lifecycle state.
List referrals
GET/v1/referrals
Authentication
Authorization: Bearer <secret key>.
Parameters
| Name | In | Required | Schema | Description |
|---|---|---|---|---|
limit | query | No | {"type":"integer","minimum":1,"maximum":100,"default":25} | |
starting_after | query | No | {"type":"string"} | A cursor (object id) for pagination; returns the page after this object. |
campaign_id | query | No | {"type":"string"} | |
referrer_id | query | No | {"type":"string"} | |
status | query | No | {"$ref":"#/components/schemas/ReferralStatus"} | |
fraud_status | query | No | {"$ref":"#/components/schemas/FraudStatus"} | Filter by fraud standing. With referrer_id, fraud_status=flagged lists the flagged referrals in one end user's history. |
Responses
200
A paginated list of referrals.
application/json schema:
{
"allOf": [
{
"$ref": "#/components/schemas/ListResponse"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Referral"
}
}
}
}
]
}400
The request was malformed or invalid.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}401
Missing or invalid API key.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}403
The API key is valid but is not permitted to call this endpoint.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}429
Too many requests.
Response headers:
{
"Retry-After": {
"description": "Seconds until the caller may retry.",
"schema": {
"type": "integer",
"minimum": 1
}
}
}application/json schema:
{
"$ref": "#/components/schemas/Error"
}Retrieve a referral
GET/v1/referrals/{referralId}
Authentication
Authorization: Bearer <secret key>.
Parameters
| Name | In | Required | Schema | Description |
|---|---|---|---|---|
referralId | path | Yes | {"type":"string"} |
Responses
200
The referral, including gate progress.
application/json schema:
{
"$ref": "#/components/schemas/Referral"
}401
Missing or invalid API key.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}403
The API key is valid but is not permitted to call this endpoint.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}404
The requested resource does not exist.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}429
Too many requests.
Response headers:
{
"Retry-After": {
"description": "Seconds until the caller may retry.",
"schema": {
"type": "integer",
"minimum": 1
}
}
}application/json schema:
{
"$ref": "#/components/schemas/Error"
}Schemas
Schema references below resolve against these definitions. Required fields, enums, bounds, and composed types are preserved from the contract.
The ReferralStatus object
The referral lifecycle state machine.
Full schema:
{
"type": "string",
"description": "The referral lifecycle state machine.",
"enum": [
"clicked",
"signed_up",
"in_progress",
"validated",
"reward_pending",
"reward_fulfilled",
"reward_failed",
"expired",
"rejected"
]
}The FraudStatus object
Where a referral stands with fraud. approved: the AI approved it. flagged: the AI rejected it and nobody has overridden that; it is not paid or billed. overridden: you overrode the flag, so it pays out.
Full schema:
{
"type": "string",
"description": "Where a referral stands with fraud. `approved`: the AI approved it. `flagged`: the AI rejected it and nobody has overridden that; it is not paid or billed. `overridden`: you overrode the flag, so it pays out.\n",
"enum": [
"approved",
"flagged",
"overridden"
]
}The ListResponse object
| Field | Type | Required | Description |
|---|---|---|---|
object | string | Yes | |
has_more | boolean | Yes | |
data | array | Yes |
Full schema:
{
"type": "object",
"required": [
"object",
"data",
"has_more"
],
"properties": {
"object": {
"type": "string",
"const": "list"
},
"has_more": {
"type": "boolean"
},
"data": {
"type": "array",
"items": {}
}
}
}The Referral object
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | |
object | string | Yes | |
status | ReferralStatus | Yes | The referral lifecycle state machine. |
fraud_status | composed | No | The referral's fraud standing; null until it validates and is decided. A flagged referral stays in the end user's referral history with fraud_status: flagged (and status: rejected) until you override it. |
campaign_id | string | Yes | |
referrer_id | string | Yes | |
referral_link_id | string or null | No | The referral link the referred user came in through, if attributed via one. |
referred_user_id | string or null | No | The customer's id for the referred end-user, once known (attribution). |
mode | Mode | No | Whether the object exists in test or live mode (determined by the API key). |
livemode | boolean | Yes | |
gate_progress | array | No | Per-condition progress toward the campaign's qualification gate (read-only — the gate itself is built in the dashboard). A fresh snapshot is taken on every engine evaluation; updated_at records when. |
score_progress | composed | No | Present for score or combined qualification modes; null for boolean-only campaigns. |
is_billable | boolean | No | Whether this referral counts toward billing (true once validated). |
signup_at | string or null | No | When the referred user signed up — anchors the campaign's qualification window. |
validated_at | string or null | No | |
created_at | string | Yes | |
updated_at | string | No | When the referral last transitioned or its gate progress was re-evaluated. |
Full schema:
{
"type": "object",
"required": [
"id",
"object",
"status",
"campaign_id",
"referrer_id",
"livemode",
"created_at"
],
"properties": {
"id": {
"type": "string",
"example": "rfl_123"
},
"object": {
"type": "string",
"const": "referral"
},
"status": {
"$ref": "#/components/schemas/ReferralStatus"
},
"fraud_status": {
"oneOf": [
{
"$ref": "#/components/schemas/FraudStatus"
},
{
"type": "null"
}
],
"description": "The referral's fraud standing; null until it validates and is decided. A flagged referral stays in the end user's referral history with `fraud_status: flagged` (and `status: rejected`) until you override it.\n"
},
"campaign_id": {
"type": "string"
},
"referrer_id": {
"type": "string"
},
"referral_link_id": {
"type": [
"string",
"null"
],
"description": "The referral link the referred user came in through, if attributed via one."
},
"referred_user_id": {
"type": [
"string",
"null"
],
"description": "The customer's id for the referred end-user, once known (attribution)."
},
"mode": {
"$ref": "#/components/schemas/Mode"
},
"livemode": {
"type": "boolean"
},
"gate_progress": {
"type": "array",
"description": "Per-condition progress toward the campaign's qualification gate (read-only — the gate itself is built in the dashboard). A fresh snapshot is taken on every engine evaluation; `updated_at` records when.\n",
"items": {
"type": "object",
"properties": {
"condition": {
"$ref": "#/components/schemas/QualificationCondition"
},
"satisfied": {
"type": "boolean"
},
"matched_events": {
"type": "integer",
"description": "Events matching the condition (name + property filters) within the window."
},
"total": {
"type": "number",
"description": "Summed contributed value across matching events (compared to the condition's `gte`)."
}
}
}
},
"score_progress": {
"oneOf": [
{
"$ref": "#/components/schemas/ScoreProgress"
},
{
"type": "null"
}
],
"description": "Present for score or combined qualification modes; null for boolean-only campaigns."
},
"is_billable": {
"type": "boolean",
"description": "Whether this referral counts toward billing (true once validated)."
},
"signup_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When the referred user signed up — anchors the campaign's qualification window."
},
"validated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "When the referral last transitioned or its gate progress was re-evaluated."
}
}
}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 your qualification gates and the referral passed Invitebase's AI fraud check. Rewards and billing only ever fire on validated.
Invitebase runs and tunes the AI fraud check. There is nothing for you to configure, and the score is not shown to you. More detail on fraud decisions is coming soon.
| 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 and the referral passed the AI fraud check. 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 | Flagged by the AI fraud check, or reversed later. Not validated; rewards are not paid and it is not billed while flagged; a reversal after validation adjusts billing. You can review a flagged referral and unblock it, which sends it down the normal payout path. |
The Mode object
Whether the object exists in test or live mode (determined by the API key).
Full schema:
{
"type": "string",
"enum": [
"test",
"live"
],
"description": "Whether the object exists in test or live mode (determined by the API key)."
}The QualificationCondition object
A single condition of a campaign's qualification gate, evaluated against the referred user's events. Read-only in the API: gates are built in the dashboard's Campaign Builder and surface here only inside a referral's gate_progress.
| Field | Type | Required | Description |
|---|---|---|---|
event | string | Yes | The event name that must occur. |
where | object | No | Property filters the event must match exactly (e.g. plan = paid). Values are scalars — matching is exact equality. |
gte | number | No | If the event carries a numeric value/count, require it to be ≥ this. |
Full schema:
{
"type": "object",
"required": [
"event"
],
"description": "A single condition of a campaign's qualification gate, evaluated against the referred user's events. Read-only in the API: gates are built in the dashboard's Campaign Builder and surface here only inside a referral's `gate_progress`.\n",
"properties": {
"event": {
"type": "string",
"description": "The event name that must occur."
},
"where": {
"type": "object",
"additionalProperties": {
"type": [
"string",
"number",
"boolean",
"null"
]
},
"description": "Property filters the event must match exactly (e.g. plan = paid). Values are scalars — matching is exact equality.\n"
},
"gte": {
"type": "number",
"exclusiveMinimum": 0,
"description": "If the event carries a numeric value/count, require it to be ≥ this."
}
}
}The ScoreProgress object
Read-only progress for score-based qualification.
| Field | Type | Required | Description |
|---|---|---|---|
threshold | number | Yes | |
total | number | Yes | |
satisfied | boolean | Yes | |
actions | array | Yes | |
mandatory | array | Yes | Boolean steps that must also be satisfied for a score-based referral. |
Full schema:
{
"type": "object",
"required": [
"threshold",
"total",
"satisfied",
"actions",
"mandatory"
],
"description": "Read-only progress for score-based qualification.",
"properties": {
"threshold": {
"type": "number",
"exclusiveMinimum": 0
},
"total": {
"type": "number",
"minimum": 0
},
"satisfied": {
"type": "boolean"
},
"actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ScoreActionProgress"
}
},
"mandatory": {
"type": "array",
"description": "Boolean steps that must also be satisfied for a score-based referral.",
"items": {
"type": "object",
"properties": {
"condition": {
"$ref": "#/components/schemas/QualificationCondition"
},
"satisfied": {
"type": "boolean"
},
"matched_events": {
"type": "integer",
"minimum": 0
},
"total": {
"type": "number",
"minimum": 0
}
}
}
}
}
}The ScoreActionProgress object
| Field | Type | Required | Description |
|---|---|---|---|
event | string | Yes | |
points | number | Yes | Points one counted occurrence contributes. |
matched_events | integer | Yes | All in-window occurrences of this event. |
contributed_events | integer | Yes | Occurrences counted after applying the optional contribution cap. |
max_contributions | integer or null | No | Maximum counted occurrences for this event, or null when unlimited. |
total | number | Yes | Total points contributed by this event type. |
Full schema:
{
"type": "object",
"required": [
"event",
"points",
"matched_events",
"contributed_events",
"total"
],
"properties": {
"event": {
"type": "string"
},
"points": {
"type": "number",
"description": "Points one counted occurrence contributes."
},
"matched_events": {
"type": "integer",
"minimum": 0,
"description": "All in-window occurrences of this event."
},
"contributed_events": {
"type": "integer",
"minimum": 0,
"description": "Occurrences counted after applying the optional contribution cap."
},
"max_contributions": {
"type": [
"integer",
"null"
],
"minimum": 1,
"description": "Maximum counted occurrences for this event, or null when unlimited."
},
"total": {
"type": "number",
"description": "Total points contributed by this event type."
}
}
}The Error object
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes |
Full schema:
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"doc_url"
],
"properties": {
"type": {
"type": "string",
"enum": [
"invalid_request_error",
"authentication_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}