---
title: "Create a referral"
method: POST
path: "/referrals"
---

# Create a referral

`POST /referrals`

Records a new referral — someone an affiliate sent your way who has now signed up.

You must identify the affiliate with exactly one of `affiliateId`, `affiliateEmail` or `promoCode`. `affiliateId` is flexible: it accepts an affiliate UUID, one of their affiliate link slugs, or a numeric click ID.

When you pass `promoCode`, the code is validated first — it must exist, be active, be unexpired, and be under both its own and its coupon's redemption limits. On success the redemption counters on the promotional code and its coupon are both incremented.

`name`, `email` and `referredUserExternalId` are always required. Referrals created here are always recorded as active.

## Request body

- NewReferral
  - `affiliateId` string — Identifies the affiliate to credit. Accepts an affiliate UUID, one of their affiliate link slugs, or a numeric click ID. Required unless `affiliateEmail` or `promoCode` is supplied.
  - `affiliateEmail` string, email — Email of the affiliate to credit. Required unless `affiliateId` or `promoCode` is supplied.
  - `promoCode` string — A promotional code belonging to the affiliate to credit. Required unless `affiliateId` or `affiliateEmail` is supplied. The code is validated for existence, active state, expiry and redemption limits, and its redemption counters are incremented on success.
  - `name` string, required — Name of the referred user
  - `email` string, email, required — Email of the referred user
  - `referredUserExternalId` string, required — The ID you maintain for this user in your own system — for example your database user ID or a Stripe customer ID.
  - `plan` string — Plan the referred user signed up on.

## Response `200`

The created referral, looked up by email after creation. Returns `null` if the referral could not be resolved.

- Referral
  - `id` string, uuid — The referral ID
  - `affiliateId` string, uuid, nullable — The affiliate credited with this referral
  - `affiliateProgramId` string, uuid, nullable — The affiliate program this referral belongs to
  - `affiliateLinkId` string, uuid, nullable — The affiliate link the referral came through
  - `commissionPlanId` string, uuid, nullable — The commission plan applied to this referral
  - `name` string, nullable — Name of the referred user
  - `email` string, email, nullable — Email of the referred user
  - `referredUserExternalId` string — The ID you maintain for this user in your own system — for example your database user ID or a Stripe customer ID.
  - `plan` string, nullable — Plan the referred user is on. Defaults to `N/A` when not supplied.
  - `subscriptionStatus` 'ACTIVE' | 'SUBMITTED' | 'DECLINED', nullable — Status of the referral. Referrals created through this API are always `ACTIVE`.
  - `submissionType` 'MANUAL' | 'AUTOMATIC', nullable — Whether the referral was submitted by hand or captured automatically
  - `referralMedium` 'COUPON' | 'LINK', nullable — How the referral was tracked
  - `source` 'UNKNOWN' | 'API' | 'INTEGRATION' | 'MANUAL' | 'IMPORTED' | 'AFFILIATE_SUBMITTED' — Where the referral came from. Referrals created through this API have `API`.
  - `totalRevenue` number, float — Total revenue attributed to this referral
  - `totalCommission` number, float — Total commission generated by this referral
  - `initialLandingPage` string, nullable — The first page the referred user landed on
  - `notes` string, nullable — Free-text notes on the referral
  - `metadata` object, nullable — Arbitrary JSON you can attach to the referral
  - `createdAt` string, date-time — When the referral was created

## Other responses

- `400` — None of `affiliateId` / `affiliateEmail` / `promoCode` was supplied; `name`, `email` or `referredUserExternalId` is missing; the promo code was not found, is inactive, has expired, has hit its redemption limit, or has no affiliate attached; or the account has reached its monthly referral limit.
- `401` — The `Authorization` header is missing, is not a `Bearer` header, or the token is not valid.
- `403` — API access is not enabled for this account.
- `404` — The affiliate program this token belongs to no longer exists.
- `429` — Too many requests for this token on this endpoint. Please slow down.

---

[API](https://skmtc.net/referly/apis/referly-api.md) · [All operations](https://skmtc.net/referly/apis/referly-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/referly/referly-api/revisions/0f506d61b9c3/schema)