Referral Codes API

Create and manage referral codes for your users.

Referral codes are unique identifiers that link a referral to a specific user. Each user can have one code per campaign.

POST/v1/links

Create a new referral link for a user. If a link already exists for this user and campaign, returns the existing link.

Parameters

Name	Type	Required	Description
userId	string	Required	Your unique identifier for the user
campaignId	string	Required	The campaign to create the link for
metadata	object	Optional	Custom metadata to attach to the link

Request Body

{
  "userId": "user_123",
  "campaignId": "camp_xxxxx",
  "metadata": {
    "source": "dashboard",
    "plan": "pro"
  }
}

Response

{
  "id": "link_xxxxx",
  "url": "https://refer.yourapp.com/abc123",
  "code": "abc123",
  "userId": "user_123",
  "campaignId": "camp_xxxxx",
  "metadata": {
    "source": "dashboard",
    "plan": "pro"
  },
  "clickCount": 0,
  "conversionCount": 0,
  "createdAt": "2024-01-15T10:30:00Z"
}

GET/v1/links/:code

Get details for a specific referral link by its code.

Parameters

Name	Type	Required	Description
code	string	Required	The referral code (from URL path)

Response

{
  "id": "link_xxxxx",
  "url": "https://refer.yourapp.com/abc123",
  "code": "abc123",
  "userId": "user_123",
  "campaignId": "camp_xxxxx",
  "clickCount": 42,
  "conversionCount": 5,
  "createdAt": "2024-01-15T10:30:00Z"
}

GET/v1/users/:userId/links

Get all referral links for a specific user.

Parameters

Name	Type	Required	Description
userId	string	Required	Your user identifier (from URL path)
campaignId	string	Optional	Filter by campaign

Response

{
  "data": [
    {
      "id": "link_xxxxx",
      "url": "https://refer.yourapp.com/abc123",
      "code": "abc123",
      "campaignId": "camp_xxxxx",
      "clickCount": 42,
      "conversionCount": 5,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

Referral links are idempotent. Creating a link for the same user and campaign will return the existing link rather than creating a duplicate.