---
title: "Create an affiliate"
method: POST
path: "/affiliates"
---

# Create an affiliate

`POST /affiliates`

Creates an affiliate in your program and gives them their first referral link.

`firstName`, `lastName` and `email` are required; the email must be unique within the program. If you do not send `affiliateLink`, a slug is generated from the email address. If you do send one and it is already taken, the request fails rather than silently picking another slug.

When `commissionRate` is omitted the affiliate inherits the program's default rate. When `affiliateStatus` is omitted, the program's auto-approve setting decides whether the affiliate starts active or pending.

Creating an affiliate also triggers the admin notification email, the affiliate welcome email (active affiliates only, unless `sendWelcomeEmail` is `false`), any automatic promo codes, and the `affiliate.created` webhook.

## Request body

- NewAffiliate
  - `firstName` string, required — First name of the affiliate
  - `lastName` string, required — Last name of the affiliate
  - `email` string, email, required — Email of the affiliate
  - `commissionRate` number, float — Commission rate for the affiliate
  - `affiliateLink` string — Optional slug for the affiliate's first referral link. If omitted, a slug is generated automatically.
  - `affiliateStatus` 'active' | 'inactive' — Status of the new affiliate. If omitted, the program's auto-approve setting decides whether the affiliate is created active or inactive.
  - `sendWelcomeEmail` boolean — Set to false to skip the affiliate welcome email. The welcome email is only sent when the affiliate is created active.
  - `commissionPlanId` string, uuid — Assign the affiliate to a commission plan in this program. Returns 400 if the plan does not exist in this program.
  - `affiliateGroupId` string, uuid — Assign the affiliate to an affiliate group in this program. Returns 400 if the group does not exist, or if commissionPlanId belongs to a different group.

## Response `200`

The created affiliate, including its generated `affiliateLinks` entry.

- Affiliate
  - `id` string, uuid — The affiliate ID
  - `firstName` string — First name of the affiliate
  - `lastName` string — Last name of the affiliate
  - `name` string, nullable — Full name of the affiliate (optional)
  - `email` string, email — Email of the affiliate
  - `password` string, nullable — Hashed Password of the affiliate (optional)
  - `emailVerified` boolean, nullable — Flag to indicate if the email has been verified
  - `image` string, nullable — Profile image URL of the affiliate
  - `detailsComplete` boolean — Flag to indicate if affiliate details are complete
  - `programId` string, uuid — The program ID that the affiliate is associated with
  - `payoutEmail` string, email — Email to be used for payouts
  - `paymentMethod` string — Payment method for the affiliate (e.g., WISE)
  - `commissionRate` number, float — Commission rate for the affiliate (0 - 100)
  - `link` string, nullable — Deprecated legacy field and almost always `null`. Read `affiliateLinks` instead.
  - `affiliateLinks` AffiliateLinkRecord[] — All affiliate link records for this affiliate. This is the source of truth for referral link slugs.
    - `id` string, uuid — Affiliate link record ID
    - `link` string — Link slug (path segment) for this affiliate
    - `userId` string, uuid, nullable — Affiliate user ID
    - `programId` string, uuid, nullable — Affiliate program ID
    - `createdAt` string, date-time — When this link was created
    - `updatedAt` string, date-time — When this link was last updated
  - `status` 'ACTIVE' | 'INACTIVE' | 'INVITED' | 'DECLINED' | 'DEACTIVATED' | 'BANNED' — Affiliate status. `INACTIVE` is shown as **Pending** in the dashboard and is kept for backwards compatibility.
  - `createdAt` string, date-time — Timestamp when the affiliate was created
  - `updatedAt` string, date-time — Timestamp when the affiliate was last updated
  - `numberOfReferredUsers` integer — Number of users referred by the affiliate
  - `numberOfClicks` integer — Number of clicks generated by the affiliate
  - `totalCommissionEarned` number, float — Total commission earned by the affiliate
  - `source` string, nullable — How the affiliate joined. Affiliates created through this API have `API`.
  - `commissionPlanId` string, uuid, nullable — The commission plan assigned to this affiliate, if any
  - `affiliateGroupId` string, uuid, nullable — The affiliate group this affiliate belongs to, if any

## Other responses

- `400` — A required field is missing, an affiliate with this email already exists, the requested affiliate link is already in use, `commissionPlanId` or `affiliateGroupId` does not exist in this program, the commission plan does not belong to the given group, or the account has reached its affiliate 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)