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

# Create referral

> Create a referral for a promoter campaign by email, uid or username, optionally splitting its commissions with split_details.



## OpenAPI

````yaml openapi-v2-referrals post /referrals
openapi: 3.0.0
info:
  title: FirstPromoter Admin API
  version: 1.0.0
  description: Admin API endpoints for managing referrals in FirstPromoter
servers:
  - url: https://api.firstpromoter.com/api/v2/company
    description: Production server
security:
  - BearerAuth: []
paths:
  /referrals:
    post:
      tags:
        - Referrals
      summary: Create referral
      description: |-
        Create a new referral 
         <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/referrals`</Tip>
      parameters:
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - promoter_campaign_id
              properties:
                email:
                  type: string
                  format: email
                  description: Email address of the referral
                uid:
                  type: string
                  description: >-
                    uid of the referral (This can be your user id from your
                    database)
                username:
                  type: string
                  description: |-
                    Username of the referral. 

                     **Note**: Reach out to us on support if you need this. It needs to be enabled before you can use it.
                promoter_campaign_id:
                  type: integer
                  description: The ID of the promoter campaign
                split_details:
                  type: array
                  description: >-
                    Distribute the referral's commissions across multiple
                    promoters. Each entry specifies a split partner and the
                    percentage of every commission they receive. The primary
                    promoter (set by the top-level `promoter_campaign_id`)
                    automatically receives the remainder. The sum of all
                    percentages must not exceed 100.
                  items:
                    type: object
                    required:
                      - promoter_campaign_id
                      - percentage
                    properties:
                      promoter_campaign_id:
                        type: integer
                        description: >-
                          The ID of the split partner's campaign enrollment
                          (`promoter_campaign.id`). This is the ID that links a
                          specific promoter to a specific campaign — not the
                          campaign ID itself.
                      percentage:
                        type: integer
                        description: >-
                          The percentage of each commission this promoter
                          receives. Must be between 0 and 100. The sum across
                          all split entries must not exceed 100.
                  example:
                    - promoter_campaign_id: 1002
                      percentage: 25
                    - promoter_campaign_id: 1003
                      percentage: 30
      responses:
        '200':
          description: Referral created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Referral'
        '401':
          description: >-
            Unauthorized — the Bearer access token is missing, invalid, expired,
            or revoked. No JSON response body is returned.
          content:
            application/json:
              schema:
                type: object
              example: {}
        '403':
          description: Forbidden
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    AccountId:
      name: Account-ID
      in: header
      required: true
      description: >-
        Account id. You can find your Account ID on Your FirstPromoter
        Dashboard. Navigate to Settings → Integrations
      schema:
        type: string
  schemas:
    Referral:
      type: object
      properties:
        id:
          type: integer
          description: Id of the referral
        email:
          type: string
          format: email
          description: Email address of the referral
        uid:
          type: string
          description: uid of the referral
        state:
          type: string
          enum:
            - subscribed
            - signup
            - active
            - cancelled
            - refunded
            - denied
            - pending
            - moved
          description: State of the referral
        metadata:
          type: object
          description: Additional metadata of the referral
        entry_source:
          type: string
          enum:
            - api
            - coupon
            - cookie
            - manual_admin
            - manual_affiliate
          description: >-
            Entry source of the referral. This shows where the referral was
            captured from. 
             **Cookie** is set if the referral was captured using the tid cookie, 
             **Coupon** is for when the referral is captured via a coupon code. 
            **Manual admin** is for when the referral is added manually by an
            admin. 

            **Manual affiliate** is for when the referral is added manually by
            an affiliate.
        created_at:
          type: string
          format: date-time
          description: Date and time when the referral was created
        customer_since:
          type: string
          format: date-time
          nullable: true
          description: Date and time when the referral became a customer
        promoter_campaign:
          $ref: '#/components/schemas/PromoterCampaign'
        fraud_check:
          type: string
          enum:
            - no_suspicion
            - same_ip_suspicion
            - same_promoter_email
            - ad_source
          description: >-
            Fraud check (suspicion) status of the referral. `no_suspicion` means
            the referral is clean or was manually cleared. `same_ip_suspicion`
            means the referral shares an IP with the promoter.
            `same_promoter_email` means the referral email matches the promoter
            email. `ad_source` means the referral arrived via a paid ad click.
        created_by_user_email:
          type: string
          format: email
          nullable: true
          description: Email address of the user who created the referral
        username:
          type: string
          nullable: true
          description: Username chosen by the referral
        split_details:
          type: array
          nullable: true
          description: >-
            The commission split configuration for this referral. Each entry
            represents a split partner. The primary promoter (the referral
            owner) receives the remainder of the commission after all split
            percentages are applied.
          items:
            type: object
            properties:
              promoter_campaign_id:
                type: integer
                description: The ID of the split partner's campaign enrollment
              promoter_id:
                type: integer
                description: The ID of the split partner (promoter)
              percentage:
                type: integer
                description: The percentage of each commission this promoter receives
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        website:
          type: string
          nullable: true
        comment:
          type: string
          nullable: true
          description: Internal note or comment on this referral
        is_expired:
          type: boolean
          description: Whether the referral has expired
    Error:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    PromoterCampaign:
      type: object
      properties:
        id:
          type: integer
          description: Id of the promoter campaign
        campaign_id:
          type: integer
          description: Id of the campaign
        promoter_id:
          type: integer
          description: Id of the promoter
        created_at:
          type: string
          format: date-time
          description: Date and time when the promoter campaign was created
        promoter:
          $ref: '#/components/schemas/Promoter'
        campaign:
          $ref: '#/components/schemas/Campaign'
    Promoter:
      type: object
      properties:
        id:
          type: integer
          description: Id of the promoter
        email:
          type: string
          format: email
          description: Email address of the promoter
        name:
          type: string
          description: Name of the promoter
    Campaign:
      type: object
      properties:
        id:
          type: integer
          description: Id of the campaign
        name:
          type: string
          description: Name of the campaign
        color:
          type: string
          nullable: true
          description: Color assigned to the campaign
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key passed as a Bearer token in the Authorization header. You can
        find your API Key on Your FirstPromoter Dashboard. Navigate to Settings
        → Integrations → Manage API Keys

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.