Referrers
End-users of your app who refer others
A Referrer is an end-user of your app who can share a referral link. The create endpoint is a create-or-identify upsert, so you can safely call it any time a user could become a referrer — from the SDKs it backs identify().
The Referrer object
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier (a UUID). |
object | string | Always referrer. |
external_id | string | Your stable id for this user. |
email | string | The user's email address. |
name | string | The user's display name. |
properties | object | Arbitrary properties you attach. |
notification_preferences | object | Per-channel notification opt-outs: { "email": boolean, "push": boolean }. Both default true. |
mode | string | test or live. |
livemode | boolean | Whether the referrer exists in live mode. |
created_at | string (date-time) | Creation time. |
Create or identify a referrer
POST/v1/referrers
Idempotent on external_id within an organization and mode: the first call creates the referrer, later calls update and return the same one (200 either way). Call it whenever a user could become a referrer.
Accepts publishable keys.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | No | Retries with the same key return the original result. |
external_id | body | string | Yes | Your stable id for this user. |
email | body | string | No | The user's email address. |
name | body | string | No | The user's display name. |
properties | body | object | No | Arbitrary properties. |
notification_preferences | body | object | No | Per-channel toggles, e.g. { "email": false, "push": false }. Omitted channels are left unchanged. |
curl https://api.invitebase.com/v1/referrers \
-H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"external_id": "usr_123",
"email": "andrew@example.com",
"name": "Andrew",
"properties": { "plan": "pro" }
}'Response — 200 OK:
{
"id": "6b1d4f9a-8e25-4c07-a3f6-1c5e9d7b2a84",
"object": "referrer",
"external_id": "usr_123",
"email": "andrew@example.com",
"name": "Andrew",
"properties": { "plan": "pro" },
"notification_preferences": { "email": true, "push": true },
"mode": "test",
"livemode": false,
"created_at": "2026-07-09T10:05:00Z"
}List referrers
GET/v1/referrers
Returns a paginated list of referrers.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer | No | 1–100, default 25. |
starting_after | query | string | No | Cursor (referrer id) for the next page. |
curl "https://api.invitebase.com/v1/referrers?limit=10" \
-H "Authorization: Bearer $INVITEBASE_SECRET_KEY"Response — 200 OK:
{
"object": "list",
"has_more": true,
"data": [
{
"id": "6b1d4f9a-8e25-4c07-a3f6-1c5e9d7b2a84",
"object": "referrer",
"external_id": "usr_123",
"email": "andrew@example.com",
"name": "Andrew",
"mode": "test",
"livemode": false,
"created_at": "2026-07-09T10:05:00Z"
}
]
}Retrieve a referrer
GET/v1/referrers/{referrerId}
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
referrerId | path | string | Yes | The referrer id. |
curl https://api.invitebase.com/v1/referrers/6b1d4f9a-8e25-4c07-a3f6-1c5e9d7b2a84 \
-H "Authorization: Bearer $INVITEBASE_SECRET_KEY"Response — 200 OK: the Referrer object. Returns 404 if the referrer does not exist.