> ## Documentation Index
> Fetch the complete documentation index at: https://developers.referly.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Referral

> Creates a new referral under the specified affiliate program. You must provide either an affiliateId, affiliateEmail, or promoCode to identify the affiliate. When using a promo code, it will be validated for expiration, redemption limits, and active status.



## OpenAPI

````yaml POST /referrals
openapi: 3.0.1
info:
  title: Referly API
  description: API for managing affiliates, referrals, and sales for SaaS businesses
  version: 1.0.0
servers:
  - url: https://www.referly.so/api/v1
security:
  - bearerAuth: []
paths:
  /referrals:
    post:
      summary: Create a new referral
      description: >-
        Creates a new referral under the specified affiliate program. You must
        provide either an affiliateId, affiliateEmail, or promoCode to identify
        the affiliate. When using a promo code, it will be validated for
        expiration, redemption limits, and active status.
      requestBody:
        description: Referral details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewReferral'
        required: true
      responses:
        '200':
          description: Referral created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Referral'
        '400':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    NewReferral:
      type: object
      required:
        - name
        - email
        - referredUserExternalId
      properties:
        affiliateId:
          type: string
          description: >-
            The affiliate ID/Link associated with the referral (required if
            affiliateEmail and promoCode are not provided)
        affiliateEmail:
          type: string
          format: email
          description: >-
            The affiliate email associated with the referral (required if
            affiliateId and promoCode are not provided)
        promoCode:
          type: string
          description: >-
            The promotional code associated with an affiliate (required if
            affiliateId and affiliateEmail are not provided). When used, the
            promo code will be validated and its redemption count will be
            incremented.
        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 external ID of the referred user
        plan:
          type: string
          description: The plan associated with the referred user
        status:
          type: string
          description: Status of the referral (active/inactive)
    Referral:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The referral ID
        affiliateId:
          type: string
          format: uuid
          description: The affiliate ID associated with the referral
        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 external ID of the referred user. This will be an ID you
            actively maintain that identifies the user on your server (for
            example, the User ID in your database, or Stripe Customer ID)
        plan:
          type: string
          description: The plan associated with the referred user
        status:
          type: string
          description: Status of the referral (active/inactive)
    Error:
      type: object
      properties:
        error:
          type: integer
          description: Error code
        message:
          type: string
          description: Error message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````