Referral Links
REST API reference for referral links
This reference is generated from the Invitebase OpenAPI contract.
Unique, attributable share links / codes.
Create a referral link
Generates a unique, attributable link/code for a referrer in a campaign. Accepts publishable or secret keys.
Authentication
Authorization: Bearer <secret key> or X-Publishable-Key header.
Parameters
| Name | In | Required | Schema | Description |
|---|---|---|---|---|
Idempotency-Key | header | No | {"type":"string"} | A unique key for one logical mutation. The same key and request replay the original result for 24 hours; using the key with a different request returns 409. |
Request body
Required.
application/json schema:
{
"$ref": "#/components/schemas/ReferralLinkCreate"
}Responses
200
The (referrer, campaign) pair already has a link — the existing link is returned, keeping previously shared URLs valid.
application/json schema:
{
"$ref": "#/components/schemas/ReferralLink"
}201
Referral link created.
application/json schema:
{
"$ref": "#/components/schemas/ReferralLink"
}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"
}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 ReferralLinkCreate object
| Field | Type | Required | Description |
|---|---|---|---|
referrer_id | string | Yes | |
campaign_id | string | Yes | |
code | string | No | Optional custom code. If omitted, one is generated. Used to preserve existing codes when migrating from another referral provider. Must be unique within the org+mode. |
Full schema:
{
"type": "object",
"required": [
"referrer_id",
"campaign_id"
],
"properties": {
"referrer_id": {
"type": "string"
},
"campaign_id": {
"type": "string"
},
"code": {
"type": "string",
"description": "Optional custom code. If omitted, one is generated. Used to preserve existing codes when migrating from another referral provider. Must be unique within the org+mode.\n"
}
}
}The ReferralLink object
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | |
object | string | Yes | |
referrer_id | string | No | |
campaign_id | string | No | |
code | string | Yes | |
url | string | Yes | |
mode | Mode | No | Whether the object exists in test or live mode (determined by the API key). |
livemode | boolean | No | |
created_at | string | No |
Full schema:
{
"type": "object",
"required": [
"id",
"object",
"url",
"code"
],
"properties": {
"id": {
"type": "string",
"example": "link_123"
},
"object": {
"type": "string",
"const": "referral_link"
},
"referrer_id": {
"type": "string"
},
"campaign_id": {
"type": "string"
},
"code": {
"type": "string",
"example": "ALEX-3F9K"
},
"url": {
"type": "string",
"format": "uri",
"example": "https://acme.refr.link/ALEX-3F9K"
},
"mode": {
"$ref": "#/components/schemas/Mode"
},
"livemode": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}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 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"
}
}
}
}
}