Referral links
Unique, attributable share links and codes
A Referral Link is the unique, attributable artifact a referrer shares: a short refr.link URL plus a human-readable code. Everything downstream — clicks, attribution, the referral lifecycle — matches on it.
The ReferralLink object
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier (a UUID). |
object | string | Always referral_link. |
referrer_id | string | The Referrer this link belongs to. |
campaign_id | string | The Campaign this link enrolls into. |
code | string | Human-readable share code, e.g. ANDREW-3F9K. Also usable for manual entry. |
url | string | The share URL, e.g. https://mycompany.refr.link/ANDREW-3F9K. Custom domains are supported. |
mode | string | test or live. |
livemode | boolean | Whether the link exists in live mode. |
created_at | string (date-time) | Creation time. |
Create a referral link
POST/v1/referral-links
Generates a unique, attributable link and code for a referrer in a campaign. From the SDKs this backs getReferralLink(campaignId).
Accepts publishable keys.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | No | Retries with the same key return the original result. |
referrer_id | body | string | Yes | The referrer to create the link for. |
campaign_id | body | string | Yes | The campaign the link enrolls into. |
curl https://api.invitebase.com/v1/referral-links \
-H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"referrer_id": "6b1d4f9a-8e25-4c07-a3f6-1c5e9d7b2a84",
"campaign_id": "7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15"
}'Response — 201 Created:
{
"id": "1e7c3b8f-5d20-4a96-8b4e-7f2a9c5d1e63",
"object": "referral_link",
"referrer_id": "6b1d4f9a-8e25-4c07-a3f6-1c5e9d7b2a84",
"campaign_id": "7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15",
"code": "ANDREW-3F9K",
"url": "https://mycompany.refr.link/ANDREW-3F9K",
"mode": "test",
"livemode": false,
"created_at": "2026-07-09T10:10:00Z"
}Returns 400 if referrer_id or campaign_id is missing or unknown. See Errors.
When someone opens the link, Invitebase records the click and creates a Referral in the clicked state. The code also works standalone — the SDKs accept it via applyCode(code) for manual entry.