Affiliates and referral links

Every affiliate in your program owns one or more referral links. A referral link is a short slug (for example jane-doe) that Referly appends to your destination URLs as a query parameter so it can attribute clicks, referrals, and sales back to that affiliate. An affiliate can have many slugs — one per campaign, channel, or landing page — and they all credit the same affiliate.

The legacy link property on the affiliate object is deprecated and is usually null. Use the affiliateLinks array, and the Links endpoints, as the source of truth for an affiliate’s referral links.

The affiliate object

Affiliate objects returned by Get Affiliate(s) and Create an Affiliate include an affiliateLinks array with one entry per slug:

Affiliate response (truncated)

{
  "id": "9f1c0b7e-4a2b-4d55-9a10-2c6b5f0a7e31",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "status": "ACTIVE",
  "commissionRate": 20,
  "link": null,
  "affiliateLinks": [
    {
      "id": "3e8a1d92-77c4-4f0e-b6a5-1d0c9e2f4b88",
      "link": "jane-doe",
      "userId": "9f1c0b7e-4a2b-4d55-9a10-2c6b5f0a7e31",
      "programId": "c2d4f6a8-0b1c-4e3d-8f5a-6b7c8d9e0f12",
      "createdAt": "2025-03-04T09:12:44.000Z",
      "updatedAt": "2025-03-04T09:12:44.000Z"
    }
  ]
}

array

Every referral link belonging to this affiliate. Each entry has id, link (the slug), userId, programId, createdAt, and updatedAt.

string | null

deprecated

Legacy single-link field. Kept for backwards compatibility and typically null. Read affiliateLinks instead.

Create an affiliate with a chosen slug

POST /affiliates requires firstName, lastName, and email. Every affiliate is created with at least one referral link, so the slug is decided at creation time.

string

The slug for the affiliate’s first referral link. If you omit it, Referly generates one from the affiliate’s email address and keeps trying until it finds an unused slug.

cURL

curl -X POST https://www.referly.so/api/v1/affiliates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "affiliateLink": "jane-doe"
  }'

If you pass an affiliateLink that another affiliate in the program already uses, the request fails with 400 and The requested affiliate link is already in use. Referly only falls back to an auto-generated slug when you left affiliateLink out. See Create an Affiliate for the full list of body fields.

Add more links to an existing affiliate

There are two ways to give an affiliate an additional slug, and both add rather than replace:

Links endpoint (recommended)
Affiliates endpoint

POST /links creates the link and returns it with its tracking URLs and stats. Identify the owner with either affiliateId or affiliateEmail.

cURL

curl -X POST https://www.referly.so/api/v1/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "link": "jane-summer",
    "affiliateEmail": "jane@example.com"
  }'

PUT /affiliates accepts an affiliateLink field. It appends a new slug and leaves the existing affiliateLinks untouched — it never renames or removes a link.

cURL

curl -X PUT https://www.referly.so/api/v1/affiliates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "affiliateId": "9f1c0b7e-4a2b-4d55-9a10-2c6b5f0a7e31",
    "affiliateLink": "jane-summer"
  }'

To rename or remove a slug, use Update Affiliate Link or Delete Affiliate Link.

Slug rules

Slugs are validated when you create or rename a link through the Links endpoints:

Only letters, numbers, and hyphens are allowed. Anything else returns 400 with Link can only contain letters, numbers, and hyphens.
A slug must be unique across your affiliate program. Reusing one returns 400 with This link already exists for this affiliate program.
The slug is the visible part of the URL your affiliates share, so short and readable works best.

Tracking URLs

A slug on its own is not a shareable URL. Get Affiliate Link(s) and Create an Affiliate Link return a fullURLs array that combines the slug with each destination URL configured on your program:

Link response (truncated)

{
  "link": "jane-doe",
  "clicks": 128,
  "referrals": 14,
  "sales": 6,
  "totalRevenue": 412.5,
  "fullURLs": [
    {
      "baseUrl": "https://example.com",
      "fullUrl": "https://example.com/?ref=jane-doe"
    },
    {
      "baseUrl": "https://example.com/pricing",
      "fullUrl": "https://example.com/pricing?ref=jane-doe"
    }
  ]
}

The query parameter name is your program’s URL modifier, which defaults to ref. Any custom URL parameters you configured on a destination URL are appended too. See Tracking parameters for how a click on one of these URLs is attributed.

Look up an affiliate or a link

The two GET endpoints let you resolve records from whichever identifier you happen to hold.

Find an affiliate

GET /affiliates returns a single affiliate when you pass an identifier, or an array of every affiliate in the program when you pass none.

string

Accepts three kinds of value: an affiliate ID, a numeric click ID, or a referral link slug. Referly tries the click ID first when the value is entirely numeric, then falls back to matching the affiliate ID or a slug in affiliateLinks.

string

The affiliate’s email address.

Resolve an affiliate from a slug

curl "https://www.referly.so/api/v1/affiliates?id=jane-doe" \
  -H "Authorization: Bearer YOUR_API_KEY"

When nothing matches, the response body is null with a 200 status rather than a 404.

Find links

GET /links accepts id, link, affiliateId, or affiliateEmail, and always returns an array. Use affiliateId or affiliateEmail to list every link an affiliate owns, each with its own clicks, referrals, sales, and totalRevenue.

List one affiliate's links

curl "https://www.referly.so/api/v1/links?affiliateEmail=jane@example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Errors

Both resources share the same authentication and error behaviour. Failures return a JSON object with an error message.

Status	When it happens
`400`	A required field is missing, an identifier does not resolve, a slug is malformed, or a slug is already in use.
`401`	The `Authorization` header is missing or malformed, or the API key is not valid.
`403`	The program does not have API access on its current plan.
`404`	The affiliate program tied to the API key no longer exists.
`429`	You exceeded the rate limit for this endpoint. Slow down and retry.

See Authentication for how to generate an API key.

Affiliate endpoints

Create, read, update, and delete affiliates.

Link endpoints

Create, read, rename, and delete referral links.

Coupons and promotional codes

Attribute sales with discount codes instead of links.

Authentication

Generate an API key and authorize your requests.

API Documentation

Affiliate Endpoints

Referral Endpoints

Sale Endpoints

Affiliate Link Endpoints

Coupon Endpoints

Promotional Code Endpoints

Affiliates and referral links

The affiliate object

Create an affiliate with a chosen slug

Add more links to an existing affiliate

Slug rules

Tracking URLs

Look up an affiliate or a link

Find an affiliate

Find links

Errors

Affiliate endpoints

Link endpoints

Coupons and promotional codes

Authentication

​The affiliate object

​Create an affiliate with a chosen slug

​Add more links to an existing affiliate

​Slug rules

​Tracking URLs

​Look up an affiliate or a link

​Find an affiliate

​Find links

​Errors

​Related

Affiliate endpoints

Link endpoints

Coupons and promotional codes

Authentication

The affiliate object

Create an affiliate with a chosen slug

Add more links to an existing affiliate

Slug rules

Tracking URLs

Look up an affiliate or a link

Find an affiliate

Find links

Errors

Related