> ## Documentation Index > Fetch the complete documentation index at: https://www.referly.so/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a Referral > 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. ## OpenAPI ````yaml POST /referrals openapi: 3.0.1 info: title: Referly API description: >- REST API for managing affiliates, referrals, sales, affiliate links, coupons and promotional codes in your Referly affiliate program. Every request must send `Authorization: Bearer `. The token is scoped to a single affiliate program, so no program ID is ever required in the request — every read and write is automatically limited to that program. Requests are rate limited per token, per endpoint and per method. version: 1.0.0 servers: - url: https://www.referly.so/api/v1 security: - bearerAuth: [] paths: /referrals: post: summary: Create a referral description: >- 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. requestBody: description: The referral to create content: application/json: schema: $ref: '#/components/schemas/NewReferral' required: true responses: '200': description: >- The created referral, looked up by email after creation. Returns `null` if the referral could not be resolved. content: application/json: schema: $ref: '#/components/schemas/Referral' '400': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/ProgramNotFound' '429': $ref: '#/components/responses/RateLimited' components: schemas: NewReferral: type: object required: - name - email - referredUserExternalId properties: affiliateId: type: string description: >- 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: type: string format: email description: >- Email of the affiliate to credit. Required unless `affiliateId` or `promoCode` is supplied. promoCode: type: string description: >- 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: type: string description: Name of the referred user email: type: string format: email description: Email of the referred user referredUserExternalId: type: string description: >- The ID you maintain for this user in your own system — for example your database user ID or a Stripe customer ID. plan: type: string default: N/A description: Plan the referred user signed up on. Referral: type: object properties: id: type: string format: uuid description: The referral ID affiliateId: type: string format: uuid nullable: true description: The affiliate credited with this referral affiliateProgramId: type: string format: uuid nullable: true description: The affiliate program this referral belongs to affiliateLinkId: type: string format: uuid nullable: true description: The affiliate link the referral came through commissionPlanId: type: string format: uuid nullable: true description: The commission plan applied to this referral name: type: string nullable: true description: Name of the referred user email: type: string format: email nullable: true description: Email of the referred user referredUserExternalId: type: string description: >- The ID you maintain for this user in your own system — for example your database user ID or a Stripe customer ID. plan: type: string nullable: true description: Plan the referred user is on. Defaults to `N/A` when not supplied. subscriptionStatus: type: string enum: - ACTIVE - SUBMITTED - DECLINED nullable: true description: >- Status of the referral. Referrals created through this API are always `ACTIVE`. submissionType: type: string enum: - MANUAL - AUTOMATIC nullable: true description: Whether the referral was submitted by hand or captured automatically referralMedium: type: string enum: - COUPON - LINK nullable: true description: How the referral was tracked source: type: string enum: - UNKNOWN - API - INTEGRATION - MANUAL - IMPORTED - AFFILIATE_SUBMITTED description: >- Where the referral came from. Referrals created through this API have `API`. totalRevenue: type: number format: float description: Total revenue attributed to this referral totalCommission: type: number format: float description: Total commission generated by this referral initialLandingPage: type: string nullable: true description: The first page the referred user landed on notes: type: string nullable: true description: Free-text notes on the referral metadata: type: object nullable: true description: Arbitrary JSON you can attach to the referral createdAt: type: string format: date-time description: When the referral was created Error: type: object properties: error: type: string description: Human readable description of what went wrong responses: Unauthorized: description: >- The `Authorization` header is missing, is not a `Bearer` header, or the token is not valid. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: API access is not enabled for this account. content: application/json: schema: $ref: '#/components/schemas/Error' ProgramNotFound: description: The affiliate program this token belongs to no longer exists. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: Too many requests for this token on this endpoint. Please slow down. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer ````