FirstPromoter Referrals API

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:
    get:
      summary: Get available referrals
      tags:
      - Referrals
      description: "Get available referrals \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/referrals`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: query
        name: q
        schema:
          type: string
        description: Search params. Searches by email, uid, username, website
      - name: ids[]
        in: query
        description: Array of referral ids to get
        required: false
        schema:
          type: array
          items:
            type: integer
      - in: query
        name: filters[type]
        schema:
          type: string
          enum:
          - lead
          - customer
        description: Filter the referrals by type (lead or customer)
      - in: query
        name: filters[promoter_id]
        schema:
          type: string
        description: Filter the referrals by a promoter id
      - in: query
        name: filters[state]
        schema:
          type: string
          enum:
          - subscribed
          - signup
          - active
          - cancelled
          - refunded
          - denied
          - pending
          - moved
        description: Filter the referrals by state
      - in: query
        name: filters[customer_since][from]
        schema:
          type: string
          format: date
        description: 'Filter referrals where customer_since is on or after this date (ISO 8601 format: YYYY-MM-DD)'
      - in: query
        name: filters[customer_since][to]
        schema:
          type: string
          format: date
        description: 'Filter referrals where customer_since is on or before this date (ISO 8601 format: YYYY-MM-DD)'
      - in: query
        name: filters[created_at][from]
        schema:
          type: string
          format: date
        description: 'Filter referrals created on or after this date (ISO 8601 format: YYYY-MM-DD)'
      - in: query
        name: filters[created_at][to]
        schema:
          type: string
          format: date
        description: 'Filter referrals created on or before this date (ISO 8601 format: YYYY-MM-DD)'
      - in: query
        name: filters[cancelled_at][from]
        schema:
          type: string
          format: date
        description: 'Filter referrals cancelled on or after this date (ISO 8601 format: YYYY-MM-DD)'
      - in: query
        name: filters[cancelled_at][to]
        schema:
          type: string
          format: date
        description: 'Filter referrals cancelled on or before this date (ISO 8601 format: YYYY-MM-DD)'
      responses:
        '200':
          description: List of referrals
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Referral'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create referral
      tags:
      - Referrals
      description: "Create a new referral \n <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. \n\n **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
        '403':
          description: Forbidden
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete referrals
      description: "With this endpoint you can delete referrals. \n <Note>If there are more than __5__ ids on the __ids__\
        \ param/field, the action will be processed asynchronously. The response for the batch status will most likely be\
        \ `in_progress`. The available statuses are `pending`, `in_progress`, `completed`, `failed` and `stopped`</Note> \n\
        \ <Tip>**HTTP Request** <br/>`DELETE https://api.firstpromoter.com/api/v2/company/referrals`</Tip>"
      tags:
      - Referrals
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchSelectionRequest'
      responses:
        '200':
          description: Batch operation completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchOperationResponse'
        '202':
          description: Batch operation accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchOperationResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /referrals/{id}:
    get:
      summary: Get referral
      tags:
      - Referrals
      description: "Get a specific referral \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/referrals/{id}`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: ID of the referral
      - in: query
        name: find_by
        schema:
          type: string
          enum:
          - email
          - uid
          - username
        description: Find by attribute
      responses:
        '200':
          description: Referral details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Referral'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
    put:
      summary: Update referral
      description: "Update a specific referral. The id can be a referral ID, email, uid, or username when used with the find_by\
        \ parameter in the request body. \n <Tip>**HTTP Request** <br/>`PUT https://api.firstpromoter.com/api/v2/company/referrals/{id}`</Tip>"
      tags:
      - Referrals
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: ID of the referral
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: Email address of the referral, this is required if the uid is null
                uid:
                  type: string
                  description: UID of the referral, this is required if the email is null
                username:
                  type: string
                  description: "Username of the referral. \n\n **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: Promoter campaign ID, you can obtain this for each promoter from the promoters endpoint. It
                    is the id that pairs a promoter to a campaign. Not the campaign id.
                find_by:
                  type: string
                  enum:
                  - email
                  - uid
                  - username
                  description: "Find by attribute. Required when id parameter is an email, uid, or username instead of an\
                    \ ID.\n\n Your request should follow the format `https://api.firstpromoter.com/api/v2/company/referrals/{email\
                    \ or uid or username}`"
                fraud_check:
                  type: string
                  enum:
                  - no_suspicion
                  - same_ip_suspicion
                  - same_promoter_email
                  - ad_source
                  description: 'Sets or clears the fraud check flag on the referral.


                    - **`no_suspicion`** — clears the flag and marks the referral as manually reviewed. Once cleared this
                    way, automatic fraud detection will not re-flag the referral.

                    - **`same_ip_suspicion`** — flags the referral because it shares an IP address with the promoter.

                    - **`same_promoter_email`** — flags the referral because its email matches the promoter''s email.

                    - **`ad_source`** — flags the referral because it arrived via a paid ad click.


                    You cannot set the same value that is already set unless the referral was previously cleared with `no_suspicion`.'
                split_details:
                  type: array
                  description: Update the commission split for this referral. Pass an array of split partners and their percentages
                    to add or replace splits. Pass an empty array (`[]`) to remove all splits. The primary promoter automatically
                    receives the remainder of the commission after all split percentages are applied. 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 updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Referral'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
  /referrals/approve:
    post:
      summary: Approve referrals
      description: "With this endpoint you can approve referrals. \n <Note>If there are more than __5__ ids on the __ids__\
        \ param/field, the action will be processed asynchronously. The response for the batch status will most likely be\
        \ `in_progress`. The available statuses are `pending`, `in_progress`, `completed`, `failed` and `stopped`</Note> \n\
        \ <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/referrals/approve`</Tip>"
      tags:
      - Referrals
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchSelectionRequest'
      responses:
        '200':
          description: Batch operation completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchOperationResponse'
        '202':
          description: Batch operation accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchOperationResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /referrals/disable:
    post:
      summary: Disable referrals
      description: "With this endpoint you can disable referrals. \n <Note>If there are more than __5__ ids on the __ids__\
        \ param/field, the action will be processed asynchronously. The response for the batch status will most likely be\
        \ `in_progress`. The available statuses are `pending`, `in_progress`, `completed`, `failed` and `stopped`</Note> \n\
        \ <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/referrals/disable`</Tip>"
      tags:
      - Referrals
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchSelectionRequest'
      responses:
        '200':
          description: Batch operation completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchOperationResponse'
        '202':
          description: Batch operation accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchOperationResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /referrals/enable:
    post:
      summary: Enable referrals
      description: "With this endpoint you can enable referrals. \n <Note>If there are more than __5__ ids on the __ids__\
        \ param/field, the action will be processed asynchronously. The response for the batch status will most likely be\
        \ `in_progress`. The available statuses are `pending`, `in_progress`, `completed`, `failed` and `stopped`</Note> \n\
        \ <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/referrals/enable`</Tip>"
      tags:
      - Referrals
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchSelectionRequest'
      responses:
        '200':
          description: Batch operation completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchOperationResponse'
        '202':
          description: Batch operation accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchOperationResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /referrals/move_to_promoter:
    post:
      summary: Move referrals to promoter
      description: "With this endpoint you can move referrals to another promoter. \n <Note>If there are more than __5__ ids\
        \ on the __ids__ param/field, the action will be processed asynchronously. The response for the batch status will\
        \ most likely be `in_progress`. The available statuses are `pending`, `in_progress`, `completed`, `failed` and `stopped`</Note>\
        \ \n <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/referrals/move_to_promoter`</Tip>"
      tags:
      - Referrals
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - promoter_campaign_id
              - selection
              properties:
                promoter_campaign_id:
                  type: integer
                  description: Destination promoter campaign ID
                move_associated_commissions:
                  type: boolean
                  description: Move associated commissions
                  enum:
                  - true
                  - false
                ids:
                  type: array
                  description: Array of selected referral ids. If there are more than __5__ ids on this param/field, the action
                    will be processed asynchronously. The response for the batch status will most likely be `in_progress`.
                    The available statuses are `pending`, `in_progress`, `completed`, `failed` and `stopped`
                  items:
                    type: integer
      responses:
        '200':
          description: Batch operation completed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  status:
                    type: string
                    enum:
                    - completed
                  total:
                    type: integer
                  selected_total:
                    type: integer
                  processed_count:
                    type: integer
                  failed_count:
                    type: integer
                  action_label:
                    type: string
                  created_at:
                    type: string
                    format: date-time
                  updated_at:
                    type: string
                    format: date-time
                  meta:
                    type: object
                  progress:
                    type: integer
                  processing_errors:
                    type: array
                    items:
                      type: string
        '202':
          description: Batch operation accepted for processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  status:
                    type: string
                  total:
                    type: integer
                  selected_total:
                    type: integer
                  processed_count:
                    type: integer
                  failed_count:
                    type: integer
                  action_label:
                    type: string
                  created_at:
                    type: string
                    format: date-time
                  updated_at:
                    type: string
                    format: date-time
                  meta:
                    type: object
                  progress:
                    type: integer
                    minimum: 0
                  processing_errors:
                    type: array
                    items:
                      type: string
                required:
                - id
                - status
                - total
                - selected_total
                - processed_count
                - failed_count
                - action_label
                - created_at
                - updated_at
                - progress
                - processing_errors
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: You don't have enough rights to perform this action
                  code:
                    type: string
                required:
                - message
                - code
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: string
                    enum:
                    - invalid_params
                    - operation_failed
                required:
                - message
                - code
  /referrals/{id}/import_events:
    post:
      summary: Import previous sales from stripe
      description: "With this endpoint you can import previous sales from Stripe. \n <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/referrals/{id}/import_events`</Tip>"
      tags:
      - Referrals
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: ID of the referral
      - in: query
        name: find_by
        schema:
          type: string
          enum:
          - email
          - uid
          - username
        description: Find by attribute
      responses:
        '202':
          description: Import task accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchOperationResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Operation failed
          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. \n **Cookie** is set\
            \ if the referral was captured using the tid cookie, \n **Coupon** is for when the referral is captured via a\
            \ coupon code. \n**Manual admin** is for when the referral is added manually by an admin. \n**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
    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
    BatchSelectionRequest:
      type: object
      properties:
        ids:
          type: array
          description: Array of selected referral ids. If there are more than __5__ ids on this param/field, the action will
            be processed asynchronously. The response for the batch status will most likely be `in_progress`. The available
            statuses are `pending`, `in_progress`, `completed`, `failed` and `stopped`
          items:
            type: integer
    BatchOperationResponse:
      type: object
      properties:
        id:
          type: integer
          description: Id of the batch operation
        status:
          type: string
          enum:
          - pending
          - completed
          description: Status of the batch operation
        total:
          type: integer
          description: Total number of items
        selected_total:
          type: integer
          description: Number of selected items
        processed_count:
          type: integer
          description: Number of processed items
        failed_count:
          type: integer
          description: Number of failed operations
        action_label:
          type: string
          description: Action identifier/ label assigned to the action
        created_at:
          type: string
          format: date-time
          description: Date and time when the batch operation was created
        updated_at:
          type: string
          format: date-time
          description: Date and time when the batch operation was updated
        meta:
          type: object
          description: Meta data of the batch operation
        progress:
          type: integer
          description: Progress of the action (0-100)
        processing_errors:
          type: array
          items:
            type: string
            description: List of processing errors
    Filters:
      type: object
      properties:
        type:
          type: string
          enum:
          - lead
          - customer
        state:
          type: string
          enum:
          - subscribed
          - signup
          - active
          - cancelled
          - refunded
          - denied
          - pending
          - moved
        created_at:
          type: object
          properties:
            from:
              type: string
              format: date
            to:
              type: string
              format: date
        customer_since:
          type: object
          properties:
            from:
              type: string
              format: date
            to:
              type: string
              format: date
        cancelled_at:
          type: object
          properties:
            from:
              type: string
              format: date
            to:
              type: string
              format: date
        campaign_id:
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
        promoter_id:
          type: integer
        entry_source:
          type: array
          items:
            type: string
            enum:
            - api
            - coupon
  

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/firstpromoter/refs/heads/main/openapi/firstpromoter-v2-referrals-openapi.yml