openapi: 3.0.1
info:
  title: FirstPromoter Admin API
  version: '2.0'
  description: REST API for managing affiliate programs, promoters, campaigns, referrals,
    rewards, and payouts in FirstPromoter. Supports pagination, filtering, and full
    CRUD operations across all affiliate program resources.
  contact:
    url: https://docs.firstpromoter.com
  license:
    name: Proprietary
    url: https://firstpromoter.com/terms
servers:
- url: https://api.firstpromoter.com/api/v2
  description: Production server
security:
- BearerAuth: []
paths:
  /company/batch_processes:
    get:
      summary: List in progress batch processes.
      description: "List batch processes that are in progress \n <Tip>**HTTP Request**\
        \ <br/>`GET https://api.firstpromoter.com/api/v2/company/batch_processes`</Tip>"
      operationId: listBatchProcesses
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: query
        name: filters[status]
        schema:
          oneOf:
          - type: string
            enum:
            - pending
            - in_progress
            - completed
            - failed
            - stopped
          - type: array
            items:
              type: string
              enum:
              - pending
              - in_progress
              - completed
              - failed
              - stopped
        description: Filter by status (array or string)
        required: false
      responses:
        '200':
          description: Successfully retrieved batch processes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BatchProcess'
        '401':
          description: Unauthenticated or missing bearer token
        '403':
          description: Forbidden - invalid user type or insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/batch_processes/{id}:
    get:
      summary: Show batch process
      description: "Show details of a specific batch process \n <Tip>**HTTP Request**\
        \ <br/>`GET https://api.firstpromoter.com/api/v2/company/batch_processes/{id}`</Tip>"
      operationId: getBatchProcess
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: path
        name: id
        schema:
          type: integer
        required: true
        description: Batch process id
      responses:
        '200':
          description: Successfully retrieved batch process
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchProcess'
        '401':
          description: Unauthenticated or missing bearer token
        '403':
          description: Forbidden - invalid user type or insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/batch_processes/progress:
    get:
      summary: Show progress
      description: "Show progress of batch process. \n <Tip>**HTTP Request** <br/>`GET\
        \ https://api.firstpromoter.com/api/v2/company/batch_processes/progress`</Tip>"
      operationId: getBatchProcessProgress
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: query
        name: filters[status]
        schema:
          oneOf:
          - type: string
            enum:
            - pending
            - in_progress
            - completed
            - failed
            - stopped
          - type: array
            items:
              type: string
              enum:
              - pending
              - in_progress
              - completed
              - failed
              - stopped
        description: Filter by status (array or string)
        required: false
      responses:
        '200':
          description: Successfully retrieved batch process progress
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: integer
                example:
                  '32': 0
                  '31': 0
                  '30': 0
        '401':
          description: Unauthenticated or missing bearer token
        '403':
          description: Forbidden - invalid user type or insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/commissions:
    get:
      summary: Get all commissions
      description: "With this endpoint you can list all rewards and commissions assigned\
        \ to a promotion, promoter, campaign or entire account using the API. \n <Tip>**HTTP\
        \ Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/commissions`</Tip>"
      tags:
      - Commissions
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: q
        in: query
        description: Search params. Searches by event_id, referral.email, referral.uid
        schema:
          type: string
      - name: ids[]
        in: query
        description: Array of commission ids to get
        required: false
        schema:
          type: array
          items:
            type: integer
      - name: filters
        in: query
        schema:
          $ref: '#/components/schemas/CommissionFilters'
      - name: sorting
        in: query
        schema:
          $ref: '#/components/schemas/CommissionSorting'
      responses:
        '200':
          description: Successfully retrieved commissions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Commission'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      summary: Create a commission
      description: "With this endpoint you can create a commission. \n <Tip>**HTTP\
        \ Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/commissions`</Tip>"
      tags:
      - Commissions
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommissionCreate'
      responses:
        '200':
          description: Successfully retrieved commissions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Commission'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /company/commissions/{id}:
    put:
      summary: Update a commission
      description: "With this endpoint you can update a commission. \n <Tip>**HTTP\
        \ Request** <br/>`PUT https://api.firstpromoter.com/api/v2/company/commissions/{id}`</Tip>"
      tags:
      - Commissions
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Id of the commission
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommissionUpdate'
      responses:
        '200':
          description: Commission updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Commission'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Commission not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /company/commissions/approve:
    post:
      summary: Approve commissions
      description: "With this endpoint you can approve commissions. \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/commissions/approve`</Tip>"
      tags:
      - Commissions
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchActionRequest'
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - completed
                      description: Status of the batch operation (always completed
                        for synchronous operations)
        '202':
          description: Batch operation accepted and processing
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - pending
                      description: Status of the batch operation (initially pending
                        for asynchronous operations)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /company/commissions/deny:
    post:
      summary: Deny commissions
      description: "With this endpoint you can deny commissions. \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/commissions/deny`</Tip>"
      tags:
      - Commissions
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchActionRequest'
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - completed
                      description: Status of the batch operation (always completed
                        for synchronous operations)
        '202':
          description: Batch operation accepted and processing
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - pending
                      description: Status of the batch operation (initially pending
                        for asynchronous operations)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /company/commissions/mark_fulfilled:
    post:
      summary: Mark nonmonetary commissions as fulfilled
      description: "With this endpoint you can mark nonmonetary commissions as fulfilled.\
        \ \n <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/commissions/mark_fulfilled`</Tip>"
      tags:
      - Commissions
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchActionRequest'
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - completed
                      description: Status of the batch operation (always completed
                        for synchronous operations)
        '202':
          description: Batch operation accepted and processing
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - pending
                      description: Status of the batch operation (initially pending
                        for asynchronous operations)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /company/commissions/mark_unfulfilled:
    post:
      summary: Mark nonmonetary commissions as unfulfilled
      description: "With this endpoint you can mark nonmonetary commissions as unfulfilled.\
        \ \n <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/commissions/mark_unfulfilled`</Tip>"
      tags:
      - Commissions
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchActionRequest'
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - completed
                      description: Status of the batch operation (always completed
                        for synchronous operations)
        '202':
          description: Batch operation accepted and processing
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - pending
                      description: Status of the batch operation (initially pending
                        for asynchronous operations)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /company/commissions/destroy:
    delete:
      summary: Delete commissions
      description: "With this endpoint you can delete commissions. \n <Tip>**HTTP\
        \ Request** <br/>`DELETE https://api.firstpromoter.com/api/v2/company/commissions/destroy`</Tip>"
      tags:
      - Commissions
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchActionRequest'
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - completed
                      description: Status of the batch operation (always completed
                        for synchronous operations)
        '202':
          description: Batch operation accepted and processing
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - pending
                      description: Status of the batch operation (initially pending
                        for asynchronous operations)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /company/commissions/generate_payouts:
    post:
      summary: Generate payouts for commissions
      description: "With this endpoint you can generate payouts for commissions. \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/commissions/generate_payouts`</Tip>"
      tags:
      - Commissions
      - Payouts
      operationId: generatePayouts
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  items:
                    type: integer
                  description: Commission IDs to generate payouts for. 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`.
              required:
              - ids
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: Operation ID
                  status:
                    type: string
                    description: Status of the operation
                  total:
                    type: integer
                    description: Total number of commissions
                  selected_total:
                    type: integer
                    description: Number of selected commissions
                  processed_count:
                    type: integer
                    description: Number of processed commissions
                  failed_count:
                    type: integer
                    description: Number of failed operations
                  action_label:
                    type: string
                    description: Action identifier
                  created_at:
                    type: string
                    format: date-time
                    description: Creation timestamp
                  updated_at:
                    type: string
                    format: date-time
                    description: Last update timestamp
                  meta:
                    type: object
                    description: Additional metadata
                  progress:
                    type: number
                    description: Progress indicator (0-1)
                  processing_errors:
                    type: array
                    description: List of processing errors
        '401':
          description: Unauthorized - Missing or invalid bearer token
  /company/emails:
    get:
      summary: Get available emails
      tags:
      - Emails
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: q
        in: query
        description: Search params. Searches by name, subject.
        required: false
        schema:
          type: string
      - name: filters[trigger_enabled]
        in: query
        description: Trigger state (Enabled / Disabled)
        required: false
        schema:
          type: string
          enum:
          - 'yes'
          - 'no'
      - name: filters[trigger_on]
        in: query
        description: Trigger on
        required: false
        schema:
          type: string
          enum:
          - not_set
          - lead_subscribed
          - lead_becomes_referral
          - promoter_signs_up
          - promoter_pending
          - promoter_accepted
          - promoter_rejected
          - promoter_blocked
          - promotion_reached_target
          - reward_created
          - reward_approved
          - reward_denied
          - fulfilment_pending
          - fulfilment_completed
          - lead_signup
          - promoter_invited
          - fulfilment_due
          - lead_pending
          - fulfilment_processing
          - new_contract_document
          - invalid_invoicing_details
          - lead_cancelled
          - count_reached
          - inactivity
          - broadcast
          - recurring
      - name: filters[sent_count][from]
        in: query
        description: sent_count from
        required: false
        schema:
          type: integer
      - name: filters[sent_count][to]
        in: query
        description: sent_count to
        required: false
        schema:
          type: integer
      - name: filters[campaign_id]
        in: query
        description: Campaign ids. Can be Integer or Array of Integers
        required: false
        schema:
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
      - name: sorting[sent_count]
        in: query
        description: The sort by sent_count direction
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: sorting[subject]
        in: query
        description: The sort by subject direction
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
    post:
      summary: Create email
      tags:
      - Emails
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - subject
              - content
              - allowed_campaign_ids
              - trigger
              properties:
                name:
                  type: string
                  description: Name of the email
                subject:
                  type: string
                  description: Subject of the email
                content:
                  type: string
                  description: Content of the email
                allowed_campaign_ids:
                  type: array
                  description: Array of allowed campaign ids
                trigger:
                  type: object
                  required:
                  - enabled
                  - trigger_on
                  - settings
                  properties:
                    enabled:
                      type: boolean
                      description: Flag to enable trigger
                    trigger_on:
                      type: string
                      enum:
                      - promoter_accepted
                      - promoter_rejected
                      - reward_created
                      - fulfilment_completed
                      - count_reached
                      - lead_signup
                      - inactivity
                      - broadcast
                      - recurring
                    settings:
                      type: object
                      properties:
                        delay_interval:
                          type: string
                          enum:
                          - second
                          - minute
                          - hour
                          - day
                          description: Delay interval is required when trigger_on
                            is 'promoter_accepted'
                        delay_value:
                          type: integer
                          description: Delay value is required when trigger_on is
                            'promoter_accepted'
                        count:
                          type: integer
                          description: Count is required when trigger_on is 'count_reached'
                        metric:
                          type: string
                          enum:
                          - clicks
                          - referrals
                          - customers
                          - cancellations
                          description: Metric is required when trigger_on is 'count_reached'
                            or 'inactivity'
                        period_in_days:
                          type: integer
                          description: Period in days is required when trigger_on
                            is 'inactivity'
                        frequency:
                          type: string
                          enum:
                          - weekly
                          - monthly
                          description: Required for recurring trigger_on
                        day:
                          type: integer
                          description: Required for recurring trigger_on. When frequency
                            == weekly -> From 0(Sunday) to 6(Saturday). When frequency
                            == montlhy -> From 1 to 31.
                        hour:
                          type: integer
                          minimum: 0
                          maximum: 23
                          description: Required for recurring trigger_on
                        minute:
                          type: integer
                          minimum: 0
                          maximum: 59
                          description: Required for recurring trigger_on
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
  /company/emails/{id}:
    get:
      summary: Get email by id
      tags:
      - Emails
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: id
        in: path
        required: true
        description: The email id
        schema:
          type: string
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
    put:
      summary: Update email
      tags:
      - Emails
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: id
        in: path
        required: true
        description: The email id
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailRequest'
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
    delete:
      summary: Delete email
      tags:
      - Emails
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: id
        in: path
        required: true
        description: The email id
        schema:
          type: string
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
  /company/emails/{id}/copy:
    post:
      summary: Copy email
      tags:
      - Emails
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: id
        in: path
        required: true
        description: The email id
        schema:
          type: string
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
  /company/emails/{id}/send_now:
    post:
      summary: Send email
      tags:
      - Emails
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: id
        in: path
        required: true
        description: The email id
        schema:
          type: string
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
  /company/emails/{id}/send_test:
    post:
      summary: Send test email
      tags:
      - Emails
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: id
        in: path
        required: true
        description: The email id
        schema:
          type: string
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
  /company/emails/template:
    get:
      summary: Get the html of the company email theme
      tags:
      - Emails
      responses:
        '200':
          description: Success
  /company/emails/custom_template:
    patch:
      summary: Updates the html of the company email theme
      tags:
      - Emails
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - html
              properties:
                html:
                  type: string
                  description: The new html content for the company email theme
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
  /company/emails/test_custom_template:
    post:
      summary: Sends a test email to current user with the custom template
      tags:
      - Emails
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
  /company/payouts:
    get:
      summary: Get all payouts
      description: "With this endpoint you can list all payouts. \n <Tip>**HTTP Request**\
        \ <br/>`GET https://api.firstpromoter.com/api/v2/company/payouts`</Tip>"
      operationId: getAdminPayouts
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: q
        in: query
        description: Search params. Searches by 'promoter.profile.first_name`, `promoter.profile.last_name`,
          `promoter.user.email`
        required: false
        schema:
          type: string
      - name: ids[]
        in: query
        description: Array of payout ids to get
        required: false
        schema:
          type: array
          items:
            type: integer
      - name: filters[status]
        in: query
        description: Filter by status
        required: false
        schema:
          type: string
          enum:
          - pending
          - completed
          - failed
          - processing
          - cancelled
      - name: filters[campaign_id]
        in: query
        description: Campaign ids. Can be Integer or Array of Integers
        required: false
        schema:
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
      - name: filters[payments_batch_id]
        in: query
        description: Payment batches ids. Can be Integer or Array of Integers
        required: false
        schema:
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
      - name: filters[due_period]
        in: query
        description: Due period
        required: false
        schema:
          type: string
          enum:
          - next
          - overdue
          - custom
      - name: filters[period_start][from]
        in: query
        description: period_start starting from date
        required: false
        schema:
          type: string
          format: date
      - name: filters[period_start][to]
        in: query
        description: period_start end at date
        required: false
        schema:
          type: string
          format: date
      - name: filters[period_end][from]
        in: query
        description: period_end starting from date
        required: false
        schema:
          type: string
          format: date
      - name: filters[period_end][to]
        in: query
        description: period_end end at date
        required: false
        schema:
          type: string
          format: date
      - name: filters[payout_method]
        in: query
        description: Payout method
        required: false
        schema:
          type: string
          enum:
          - paypal
          - bank
          - wise
          - crypto
          - custom
          - dots
          - not_set
      - name: filters[promoter_id]
        in: query
        description: Promoter id
        required: false
        schema:
          type: integer
      - name: filters[only_payable]
        in: query
        description: Only payable payouts
        required: false
        schema:
          type: boolean
      - name: filters[group_ref]
        in: query
        description: Group reference
        required: false
        schema:
          type: string
      - name: filters[fraud_suspicions]
        in: query
        description: Fraud suspicions. Multiple values can be passed as an array.
          Send ['no_suspicion'] to filter promoters with no fraud suspicions
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - same_ip_suspicion
            - same_promoter_email
            - ad_source
            - no_suspicion
      - name: sorting[amount]
        in: query
        description: The sort by amount direction
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: sorting[period_start]
        in: query
        description: Period start
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: sorting[period_end]
        in: query
        description: Period end
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Payout'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/payouts/stats:
    get:
      summary: Get payout stats
      description: "This endpoint returns statistics about payouts. \n <Tip>**HTTP\
        \ Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/payouts/stats`</Tip>"
      operationId: getAdminPayoutStats
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: stats_by[paid_period]
        in: query
        description: Shows the stats by payout period only for paid payouts
        required: false
        schema:
          type: boolean
      - name: stats_by[status]
        in: query
        description: Shows the stats by status (pending, failed, processing, completed)
        required: false
        schema:
          type: boolean
      - name: stats_by[payout_method]
        in: query
        description: Shows the stats by payout method
        required: false
        schema:
          type: boolean
      - name: filters[status]
        in: query
        description: Filter by status
        required: false
        schema:
          type: string
          enum:
          - pending
          - completed
          - failed
          - processing
          - cancelled
      - name: filters[campaign_id]
        in: query
        description: Campaign ids. Can be Integer or Array of Integers
        required: false
        schema:
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutStats'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/payouts/due_stats:
    get:
      summary: Get due payout stats
      description: "This endpoint returns statistics about due payouts. \n <Tip>**HTTP\
        \ Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/payouts/due_stats`</Tip>"
      operationId: getAdminPayoutDueStats
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: q
        in: query
        description: Search params. Searches by 'promoter.profile.first_name`, `promoter.profile.last_name`,
          `promoter.user.email`
        required: false
        schema:
          type: string
      - name: filters[status]
        in: query
        description: Filter by status
        required: false
        schema:
          type: string
          enum:
          - pending
          - completed
          - failed
          - processing
          - cancelled
      - name: filters[campaign_id]
        in: query
        description: Campaign ids. Can be Integer or Array of Integers
        required: false
        schema:
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutDueStats'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/payouts/group_by_promoters:
    get:
      summary: Get all payouts grouped by promoters
      description: "This endpoint returns all payouts but grouped by promoters. \n\
        \ <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/payouts/group_by_promoters`</Tip>"
      operationId: getAdminPayoutsGroupedByPromoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: q
        in: query
        description: Search params. Searches by 'promoter.profile.first_name`, `promoter.profile.last_name`,
          `promoter.user.email`
        required: false
        schema:
          type: string
      - name: filters[status]
        in: query
        description: Filter by status
        required: false
        schema:
          type: string
          enum:
          - pending
          - completed
          - failed
          - processing
          - cancelled
      - name: filters[campaign_id]
        in: query
        description: Campaign ids. Can be Integer or Array of Integers
        required: false
        schema:
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
      - name: include_payout_method_details
        in: query
        description: Set it true to include the payout_method_details
        required: false
        schema:
          type: boolean
      - name: filters[min_payment]
        in: query
        description: Filters payouts by the minimum payment amount possible
        required: false
        schema:
          type: integer
      - name: filters[invoiceable]
        in: query
        description: Filters payouts by invoiceable
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          - not_set
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutsGroupedByPromoters'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/payouts/create_payments_batch:
    post:
      summary: Create payments batch
      description: "This endpoint creates a new payments batch. \n <Tip>**HTTP Request**\
        \ <br/>`POST https://api.firstpromoter.com/api/v2/company/payouts/create_payments_batch`</Tip>"
      operationId: createPaymentsBatch
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                method:
                  type: string
                  enum:
                  - paypal
                  - bank
                  - wise
                  - crypto
                  - dots
                  description: Payment method
              required:
              - method
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentsBatch'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/payouts/mark_as_paid:
    post:
      summary: Mark payouts as paid
      description: "Marks selected payouts as paid \n <Tip>**HTTP Request** <br/>`POST\
        \ https://api.firstpromoter.com/api/v2/company/payouts/mark_as_paid`</Tip>"
      operationId: markPayoutsAsPaid
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  $ref: '#/components/schemas/Ids'
              required:
              - ids
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchActionResult'
        '202':
          description: Accepted (Processing in background)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchActionResult'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/payouts/mark_as_unpaid:
    post:
      summary: Mark payouts as unpaid
      description: "Marks selected payouts as unpaid \n <Tip>**HTTP Request** <br/>`POST\
        \ https://api.firstpromoter.com/api/v2/company/payouts/mark_as_unpaid`</Tip>"
      operationId: markPayoutsAsUnpaid
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  $ref: '#/components/schemas/Ids'
              required:
              - ids
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchActionResult'
        '202':
          description: Accepted (Processing in background)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchActionResult'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/payouts/destroy:
    delete:
      summary: Delete payouts
      description: "Deletes selected payouts \n <Tip>**HTTP Request** <br/>`DELETE\
        \ https://api.firstpromoter.com/api/v2/company/payouts/destroy`</Tip>"
      operationId: deletePayouts
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  $ref: '#/components/schemas/Ids'
              required:
              - ids
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchActionResult'
        '202':
          description: Accepted (Processing in background)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchActionResult'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/promo_codes:
    get:
      summary: Get promo codes
      operationId: getPromoCodes
      description: "With this endpoint you can list all promo codes. \n <Tip>**HTTP\
        \ Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/promo_codes`</Tip>"
      tags:
      - Promo Codes
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: promoter_campaign_id
        in: query
        description: Filters promo codes by promoter campaign id
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: List of promo codes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PromoCode'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create promo code (Stripe Only)
      operationId: createPromoCode
      description: "With this endpoint you can create a new promo code. \n <Tip>**HTTP\
        \ Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/promo_codes`</Tip>"
      tags:
      - Promo Codes
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - code
              - reward_id
              - promoter_campaign_id
              properties:
                code:
                  type: string
                  description: Code of the promo code
                description:
                  type: string
                  description: Description of the promo code
                reward_id:
                  type: integer
                  description: ID of the reward
                promoter_campaign_id:
                  type: integer
                  description: ID of the promoter campaign
                metadata:
                  type: object
                  description: Metadata of the promo code
                details:
                  type: object
                  description: Details of the promo code
      responses:
        '200':
          description: Created promo code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoCode'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/promo_codes/{id}:
    get:
      summary: Get promo code by id
      operationId: getPromoCode
      tags:
      - Promo Codes
      description: "With this endpoint you can get the details of a specific promo\
        \ code. \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/promo_codes/{id}`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: id
        in: path
        description: ID of the promo code
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Promo code details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoCode'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update promo code by id
      description: "Update promo code by id. Can not be updated if archived and ext_id\
        \ present. \n<Tip>**HTTP Request** <br/>`PUT https://api.firstpromoter.com/api/v2/company/promo_codes/{id}`</Tip>"
      operationId: updatePromoCode
      tags:
      - Promo Codes
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: id
        in: path
        description: ID of the promo code
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
                  description: Code of the promo code
                description:
                  type: string
                  description: Description of the promo code
                promoter_campaign_id:
                  type: integer
                  description: ID of the promoter campaign
                metadata:
                  type: object
                  description: Metadata of the promo code
                details:
                  type: object
                  description: Details of the promo code
      responses:
        '200':
          description: Updated promo code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoCode'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Archive promo code by id
      description: "Archive promo code by id. \n<Tip>**HTTP Request** <br/>`DELETE\
        \ https://api.firstpromoter.com/api/v2/company/promo_codes/{id}`</Tip>"
      operationId: archivePromoCode
      tags:
      - Promo Codes
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: id
        in: path
        description: ID of the promo code
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Promo code archived successfully
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/promoter_campaigns:
    get:
      summary: Get available promoter campaigns
      description: "With this endpoint you can list all promoter campaigns. \n <Tip>**HTTP\
        \ Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/promoter_campaigns`</Tip>"
      tags:
      - Promoter Campaigns
      parameters:
      - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: List of promoter campaigns
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PromoterCampaign'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/promoter_campaigns/search:
    get:
      summary: 'Returns results for promoter campaigns dropdown search. Max results:
        5'
      description: "With this endpoint you can search for promoter campaigns. \n <Tip>**HTTP\
        \ Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/promoter_campaigns/search?q=...`</Tip>"
      tags:
      - Promoter Campaigns
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: query
        name: q
        required: true
        schema:
          type: string
        description: Search params
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PromoterCampaign'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/promoter_campaigns/{id}:
    put:
      summary: Update promoter campaign
      operationId: updatePromoterCampaign
      description: "With this endpoint you can update a promoter campaign. \n <Tip>**HTTP\
        \ Request** <br/>`PUT https://api.firstpromoter.com/api/v2/company/promoter_campaigns/{id}`</Tip>"
      tags:
      - Promoter Campaigns
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: path
        name: id
        required: true
        schema:
          type: integer
        description: Promoter campaign ID. This ID is not the promoter’s ID or the
          campaign’s ID. It’s the linking record that defines the promoter’s participation
          in that campaign. You can find this id in each object in the promoter_campaigns
          array when you get the details of the promoter.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ref_token:
                  type: string
                state:
                  type: string
                  enum:
                  - pending
                  - accepted
                  - rejected
                  - blocked
                  - inactive
                coupon:
                  type: string
                display_coupon:
                  type: string
                direct_url:
                  type: string
                rewards_for_promoters:
                  type: array
                  items:
                    $ref: '#/components/schemas/RewardConfig'
                rewards_for_referrals:
                  type: array
                  items:
                    $ref: '#/components/schemas/RewardConfig'
                promoter_rewards_customized:
                  type: boolean
                referral_rewards_customized:
                  type: boolean
      responses:
        '200':
          description: Updated promoter campaign
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoterCampaign'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/promoter_campaigns/{id}/referral_links:
    get:
      summary: Get promoter campaign referral links
      operationId: getReferralLinksAssociatedWithThisPromoterCampaign
      description: With this endpoint you can get the referral links associated with
        this promoter campaign. <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/promoter_campaigns/{id}/referral_links`</Tip>
      tags:
      - Promoter Campaigns
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: path
        name: id
        required: true
        schema:
          type: integer
        description: Promoter campaign ID
      responses:
        '200':
          description: List of referral links
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReferralLink'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/promoter_campaigns/{id}/chart_data:
    get:
      summary: Get data used for chart
      tags:
      - Promoter Campaigns
      operationId: getPromoterCampaignChartData
      description: With this endpoint you can get the data used for charts.<Tip>**HTTP
        Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/promoter_campaigns/{id}/chart_data`</Tip>
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: path
        name: id
        required: true
        schema:
          type: integer
        description: Promoter campaign ID. This ID is not the promoter’s ID or the
          campaign’s ID. It’s the linking record that defines the promoter’s participation
          in that campaign. You can find this id in each object in the promoter_campaigns
          array when you get the details of the promoter.
      - in: query
        name: period_from
        required: true
        schema:
          type: string
          format: date
      - in: query
        name: period_to
        required: true
        schema:
          type: string
          format: date
      - in: query
        name: selection
        required: true
        schema:
          type: string
          enum:
          - revenue
          - clicks
          - referrals
          - customers
          - cancellations
      - in: query
        name: with_totals
        required: false
        schema:
          type: boolean
        description: If true, it will also return the totals for the period
      responses:
        '200':
          description: Chart data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChartData'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/promoters:
    get:
      summary: Get available promoters
      description: "With this endpoint you can list all promoters. \n <Tip>**HTTP\
        \ Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/promoters`</Tip>"
      operationId: getPromoters
      tags:
      - Promoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: q
        in: query
        description: Search params for promoters, search using, email, name or ref_id
        required: false
        schema:
          type: string
      - name: ids[]
        in: query
        description: Array of promoter ids to get
        required: false
        schema:
          type: array
          items:
            type: integer
      - name: filters
        in: query
        description: Filter params
        required: false
        schema:
          $ref: '#/components/schemas/PromoterFilters'
      - name: sorting
        in: query
        description: Sorting params
        required: false
        schema:
          type: object
          properties:
            clicks_count:
              type: string
              enum:
              - asc
              - desc
            referrals_count:
              type: string
              enum:
              - asc
              - desc
            customers_count:
              type: string
              enum:
              - asc
              - desc
            revenue_amount:
              type: string
              enum:
              - asc
              - desc
            joined_at:
              type: string
              enum:
              - asc
              - desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Promoter'
                    description: List of Promoters
                  meta:
                    type: object
                    properties:
                      pending_count:
                        type: integer
        '401':
          description: Unauthorized
    post:
      summary: Create promoter
      description: "With this endpoint you can create a promoter. \n <Tip>**HTTP Request**\
        \ <br/>`POST https://api.firstpromoter.com/api/v2/company/promoters`</Tip>"
      operationId: createPromoter
      tags:
      - Promoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromoterCreate'
      responses:
        '201':
          description: Promoter created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Promoter'
        '401':
          description: Unauthorized
  /company/promoters/{id}:
    get:
      summary: Get promoter details
      description: "With this endpoint you can get the details of a promoter. \n <Tip>**HTTP\
        \ Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/promoters/{id}`</Tip>"
      operationId: getPromoter
      tags:
      - Promoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: id
        description: The promoter's numeric ID, or the value of the attribute specified
          in `find_by` (e.g. an email address, auth token, ref token, promo code,
          or cust_id)
        in: path
        required: true
        schema:
          type: string
      - name: find_by
        in: query
        description: Find by attribute
        schema:
          type: string
          enum:
          - email
          - cust_id
          - auth_token
          - ref_token
          - promo_code
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Promoter'
        '401':
          description: Unauthorized
    put:
      summary: Update promoter
      operationId: updatePromoter
      description: "With this endpoint you can update a promoter. \n <Tip>**HTTP Request**\
        \ <br/>`PUT https://api.firstpromoter.com/api/v2/company/promoters/{id}`</Tip>"
      tags:
      - Promoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: id
        in: path
        description: Id of the promoter
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromoterUpdate'
      responses:
        '200':
          description: Promoter updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Promoter'
        '401':
          description: Unauthorized
  /company/promoters/{id}/chart_data:
    get:
      summary: Get data used for chart
      description: With this endpoint you can get the data used for charts.<Tip>**HTTP
        Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/promoters/{id}/chart_data`</Tip>
      operationId: getPromoterChartData
      tags:
      - Promoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: id
        in: path
        required: true
        description: Id of the promoter
        schema:
          type: integer
      - name: period_from
        description: From date of the period for the chart, ISO date format (YYYY-MM-DD)
        in: query
        required: true
        schema:
          type: string
          format: date
      - name: period_to
        in: query
        required: true
        schema:
          type: string
          format: date
      - name: selection
        in: query
        required: true
        schema:
          type: string
          enum:
          - revenue
          - clicks
          - referrals
          - customers
          - cancellations
      responses:
        '200':
          description: Chart data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoterChartData'
        '401':
          description: Unauthorized
  /company/promoters/accept:
    post:
      summary: Accept promoters
      description: "With this endpoint you can accept promoters. \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/promoters/accept`</Tip>"
      operationId: acceptPromoters
      tags:
      - Promoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - campaign_id
              properties:
                campaign_id:
                  type: integer
                  description: The ID of the campaign promoter will be accepted to
                ids:
                  $ref: '#/components/schemas/Ids'
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - completed
                      description: Status of the batch operation (always completed
                        for synchronous operations)
        '202':
          description: Batch operation accepted and processing
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - pending
                      description: Status of the batch operation (initially pending
                        for asynchronous operations)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /company/promoters/reject:
    post:
      summary: Reject promoters
      description: "With this endpoint you can reject promoters. \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/promoters/reject`</Tip>"
      operationId: rejectPromoters
      tags:
      - Promoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - campaign_id
              properties:
                campaign_id:
                  type: integer
                  description: The ID of the campaign promoter will be rejected from
                ids:
                  $ref: '#/components/schemas/Ids'
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - completed
                      description: Status of the batch operation (always completed
                        for synchronous operations)
        '202':
          description: Batch operation accepted and processing
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - pending
                      description: Status of the batch operation (initially pending
                        for asynchronous operations)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /company/promoters/block:
    post:
      summary: Block promoters
      description: "With this endpoint you can block promoters. \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/promoters/block`</Tip>"
      operationId: blockPromoters
      tags:
      - Promoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - campaign_id
              properties:
                campaign_id:
                  type: integer
                  description: The ID of the campaign promoter will be blocked from
                ids:
                  $ref: '#/components/schemas/Ids'
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - completed
                      description: Status of the batch operation (always completed
                        for synchronous operations)
        '202':
          description: Batch operation accepted and processing
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - pending
                      description: Status of the batch operation (initially pending
                        for asynchronous operations)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /company/promoters/archive:
    post:
      summary: Archive promoters
      description: "With this endpoint you can archive promoters. \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/promoters/archive`</Tip>"
      operationId: archivePromoters
      tags:
      - Promoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  $ref: '#/components/schemas/Ids'
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - completed
                      description: Status of the batch operation (always completed
                        for synchronous operations)
        '202':
          description: Batch operation accepted and processing
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - pending
                      description: Status of the batch operation (initially pending
                        for asynchronous operations)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /company/promoters/move_to_campaign:
    post:
      summary: Move promoters to campaign
      description: "With this endpoint you can move promoters from one campaign to\
        \ another. \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/promoters/move_to_campaign`</Tip>"
      operationId: movePromotersToCampaign
      tags:
      - Promoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - selection
              - from_campaign_id
              - to_campaign_id
              properties:
                ids:
                  $ref: '#/components/schemas/Ids'
                from_campaign_id:
                  type: integer
                  description: The ID of the campaign promoter will be moved from
                to_campaign_id:
                  type: integer
                  description: The ID of the campaign promoter will be moved to
                drip_emails:
                  type: boolean
                  description: If true, it will send an email to the promoter for
                    this action
                soft_move_referrals:
                  type: boolean
                  description: If `true`, move referrals to NEW campaign and future
                    commissions from existing referrals will be tracked in the NEW
                    campaign. However, if `false`, keep referrals in the old campaign
                    and future commissions from existing referrals will be tracked
                    in the OLD campaign.
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - completed
                      description: Status of the batch operation (always completed
                        for synchronous operations)
        '202':
          description: Batch operation accepted and processing
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - pending
                      description: Status of the batch operation (initially pending
                        for asynchronous operations)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /company/promoters/add_to_campaign:
    post:
      summary: Add promoters to campaign
      description: "With this endpoint you can add promoters to a campaign. \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/promoters/add_to_campaign`</Tip>"
      operationId: addPromotersToCampaign
      tags:
      - Promoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - selection
              - campaign_id
              properties:
                ids:
                  $ref: '#/components/schemas/Ids'
                campaign_id:
                  type: integer
                  description: The ID of the campaign promoter will be added to
                drip_emails:
                  type: boolean
                  description: If true, it will send an email to the promoter for
                    this action
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - completed
                      description: Status of the batch operation (always completed
                        for synchronous operations)
        '202':
          description: Batch operation accepted and processing
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - pending
                      description: Status of the batch operation (initially pending
                        for asynchronous operations)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /company/promoters/assign_parent:
    post:
      summary: Assign a parent promoter
      description: "With this endpoint you can assign a parent promoter to your promoters.\
        \ \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/promoters/assign_parent`</Tip>"
      operationId: acceptPromoters
      tags:
      - Promoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - parent_promoter_id
              properties:
                parent_promoter_id:
                  type: integer
                  description: The ID of the parent promoter you want to assign the
                    promoters to
                ids:
                  $ref: '#/components/schemas/Ids'
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - completed
                      description: Status of the batch operation (always completed
                        for synchronous operations)
        '202':
          description: Batch operation accepted and processing
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - pending
                      description: Status of the batch operation (initially pending
                        for asynchronous operations)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /company/promoters/restore:
    post:
      summary: Restore promoters
      description: "With this endpoint you can restore promoters. \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/promoters/restore`</Tip>"
      operationId: restorePromoters
      tags:
      - Promoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  $ref: '#/components/schemas/Ids'
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - completed
                      description: Status of the batch operation (always completed
                        for synchronous operations)
        '202':
          description: Batch operation accepted and processing
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - pending
                      description: Status of the batch operation (initially pending
                        for asynchronous operations)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /company/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
  /company/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}`"
                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
  /company/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
  /company/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
  /company/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
  /company/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
  /company/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'
  /company/reports/overview:
    get:
      summary: Get reports for overview
      description: "Get reports for overview \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/reports/overview`</Tip>"
      tags:
      - Reports
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: columns
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
            enum:
            - active_customers
            - monthly_churn
            - clicks_count
            - net_revenue_amount
            - revenue_amount
            - referrals_count
            - customers_count
            - sales_count
            - refunds_count
            - cancelled_customers_count
            - promoter_earnings_amount
            - non_link_customers
            - referrals_to_customers_cr
            - 3m_epc
            - 6m_epc
            - clicks_to_customers_cr
            - clicks_to_referrals_cr
            - promoter_paid_amount
            - signups_count
      - name: q
        in: query
        required: false
        schema:
          type: string
      - name: group_by
        in: query
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
      - name: start_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: end_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: sorting
        in: query
        required: false
        schema:
          type: object
          additionalProperties:
            type: string
            enum:
            - asc
            - desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    period:
                      type: string
                    id:
                      type: string
                    data:
                      type: object
                      properties:
                        revenue_amount:
                          type: number
                        net_revenue_amount:
                          type: number
                        promoter_earnings_amount:
                          type: number
                        customers_count:
                          type: integer
                        referrals_count:
                          type: integer
                        clicks_count:
                          type: integer
                        active_customers:
                          type: integer
                        3m_epc:
                          type: number
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: string
  /company/reports/campaigns:
    get:
      summary: Get reports for campaigns
      description: With this endpoint you can get the report data grouped by campaigns.<Tip>**HTTP
        Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/reports/campaigns`</Tip>
      tags:
      - Reports
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: columns
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
            enum:
            - active_customers
            - monthly_churn
            - clicks_count
            - net_revenue_amount
            - revenue_amount
            - referrals_count
            - customers_count
            - sales_count
            - refunds_count
            - cancelled_customers_count
            - promoter_earnings_amount
            - non_link_customers
            - referrals_to_customers_cr
            - 3m_epc
            - 6m_epc
            - clicks_to_customers_cr
            - clicks_to_referrals_cr
            - promoter_paid_amount
            - signups_count
      - name: q
        in: query
        required: false
        schema:
          type: string
      - name: group_by
        in: query
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
      - name: start_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: end_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: sorting
        in: query
        required: false
        schema:
          type: object
          additionalProperties:
            type: string
            enum:
            - asc
            - desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    campaign:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                        color:
                          type: string
                    id:
                      type: integer
                    data:
                      type: object
                      properties:
                        revenue_amount:
                          type: number
                        net_revenue_amount:
                          type: number
                        promoter_earnings_amount:
                          type: number
                        customers_count:
                          type: integer
                        referrals_count:
                          type: integer
                        clicks_count:
                          type: integer
                        active_customers:
                          type: integer
                        3m_epc:
                          type: number
                    sub_data:
                      type: array
                      items:
                        type: object
                        properties:
                          period:
                            type: string
                          id:
                            type: string
                          data:
                            type: object
                            properties:
                              revenue_amount:
                                type: number
                              net_revenue_amount:
                                type: number
                              promoter_earnings_amount:
                                type: number
                              customers_count:
                                type: integer
                              referrals_count:
                                type: integer
                              clicks_count:
                                type: integer
                              active_customers:
                                type: integer
                              3m_epc:
                                type: number
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: string
  /company/reports/promoters:
    get:
      summary: Get reports for promoters
      description: ' With this endpoint you can get the report data grouped by promoters.<Tip>**HTTP
        Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/reports/promoters`</Tip>'
      tags:
      - Reports
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: columns
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
            enum:
            - active_customers
            - monthly_churn
            - clicks_count
            - net_revenue_amount
            - revenue_amount
            - referrals_count
            - customers_count
            - sales_count
            - refunds_count
            - cancelled_customers_count
            - promoter_earnings_amount
            - non_link_customers
            - referrals_to_customers_cr
            - 3m_epc
            - 6m_epc
            - clicks_to_customers_cr
            - clicks_to_referrals_cr
            - promoter_paid_amount
            - signups_count
        description: Fields to be included in the report
      - name: q
        in: query
        required: false
        schema:
          type: string
        description: Search query string
      - name: group_by
        in: query
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
        description: Time period grouping
      - name: start_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
        description: Start date for the report period
      - name: end_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
        description: End date for the report period
      - name: sorting
        in: query
        required: false
        schema:
          type: object
          additionalProperties:
            type: string
            enum:
            - asc
            - desc
        description: Sorting parameters
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    promoter:
                      type: object
                      properties:
                        id:
                          type: integer
                        email:
                          type: string
                          format: email
                        name:
                          type: string
                      required:
                      - id
                      - email
                      - name
                    id:
                      type: integer
                    data:
                      type: object
                      properties:
                        revenue_amount:
                          type: number
                        net_revenue_amount:
                          type: number
                        promoter_earnings_amount:
                          type: number
                        customers_count:
                          type: integer
                        referrals_count:
                          type: integer
                        clicks_count:
                          type: integer
                        active_customers:
                          type: integer
                        3m_epc:
                          type: number
                    sub_data:
                      type: array
                      items:
                        type: object
                        properties:
                          period:
                            type: string
                          id:
                            type: string
                          data:
                            type: object
                            properties:
                              revenue_amount:
                                type: number
                              net_revenue_amount:
                                type: number
                              promoter_earnings_amount:
                                type: number
                              customers_count:
                                type: integer
                              referrals_count:
                                type: integer
                              clicks_count:
                                type: integer
                              active_customers:
                                type: integer
                              3m_epc:
                                type: number
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized
                  code:
                    type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid user type
                  code:
                    type: string
                    example: forbidden
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'param is missing or the value is empty: columns'
                  code:
                    type: string
                    example: invalid_params
  /company/reports/traffic_sources:
    get:
      summary: Get reports for traffic sources
      description: "With this endpoint you can get the report data grouped by traffic\
        \ sources. \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/reports/traffic_sources`</Tip>"
      tags:
      - Reports
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: columns
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
            enum:
            - clicks_count
            - revenue_amount
            - promoter_earnings_amount
            - referrals_count
            - customers_count
            - sales_count
            - refunds_count
            - cancelled_customers_count
            - referrals_to_customers_cr
            - clicks_to_customers_cr
            - clicks_to_referrals_cr
        description: Fields to be included in the report
      - name: q
        in: query
        required: false
        schema:
          type: string
        description: Search query string
      - name: group_by
        in: query
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
        description: Time period grouping
      - name: start_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
        description: Start date for the report period
      - name: end_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
        description: End date for the report period
      - name: sorting
        in: query
        required: false
        schema:
          type: object
          additionalProperties:
            type: string
            enum:
            - asc
            - desc
        description: Sorting parameters
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    source:
                      type: string
                    id:
                      type: string
                    data:
                      type: object
                      properties:
                        clicks_count:
                          type: integer
                        revenue_amount:
                          type: number
                        promoter_earnings_amount:
                          type: number
                        referrals_count:
                          type: integer
                        customers_count:
                          type: integer
                        sales_count:
                          type: integer
                        refunds_count:
                          type: integer
                        cancelled_customers_count:
                          type: integer
                        referrals_to_customers_cr:
                          type: number
                        clicks_to_customers_cr:
                          type: number
                        clicks_to_referrals_cr:
                          type: number
                    sub_data:
                      type: array
                      items:
                        type: object
                        properties:
                          period:
                            type: string
                          id:
                            type: string
                          data:
                            type: object
                            properties:
                              clicks_count:
                                type: integer
                              revenue_amount:
                                type: number
                              promoter_earnings_amount:
                                type: number
                              referrals_count:
                                type: integer
                              customers_count:
                                type: integer
                              sales_count:
                                type: integer
                              refunds_count:
                                type: integer
                              cancelled_customers_count:
                                type: integer
                              referrals_to_customers_cr:
                                type: number
                              clicks_to_customers_cr:
                                type: number
                              clicks_to_referrals_cr:
                                type: number
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized
                  code:
                    type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid user type
                  code:
                    type: string
                    example: forbidden
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'param is missing or the value is empty: columns'
                  code:
                    type: string
                    example: invalid_params
  /company/reports/urls:
    get:
      summary: Get reports for URLs
      description: With this endpoint you can get the report data grouped by URLs.<Tip>**HTTP
        Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/reports/urls`</Tip>
      tags:
      - Reports
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: columns
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
            enum:
            - clicks_count
            - revenue_amount
            - promoter_earnings_amount
            - referrals_count
            - customers_count
            - sales_count
            - refunds_count
            - cancelled_customers_count
            - referrals_to_customers_cr
            - clicks_to_customers_cr
            - clicks_to_referrals_cr
            - url
      - name: q
        in: query
        required: false
        schema:
          type: string
      - name: group_by
        in: query
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
      - name: start_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: end_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: sorting
        in: query
        required: false
        schema:
          type: object
          additionalProperties:
            type: string
            enum:
            - asc
            - desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/URLsResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Unprocessable Entity
  /company/reports/download:
    get:
      summary: Download reports
      description: With this endpoint you can download reports.<Tip>**HTTP Request**
        <br/>`GET https://api.firstpromoter.com/api/v2/company/reports/download`</Tip>
      tags:
      - Reports
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: report_type
        in: query
        required: true
        schema:
          type: string
          enum:
          - overview
          - campaigns
          - promoters
          - traffic_sources
          - urls
      - name: totals
        in: query
        required: false
        schema:
          type: boolean
      - name: columns
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
      - name: group_by
        in: query
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
      - name: start_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: end_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: CSV file download
          content:
            text/csv:
              schema:
                type: string
                format: binary
        '202':
          description: Accepted - async processing started
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Unprocessable Entity
  /track/signup:
    post:
      description: Capture a lead when they sign-up or fill an optin form. This endpoint
        is used to track leads and sign-ups. It's not for tracking the actual sales
        and commissions. <br/>  <br/> Sign-ups are tracked as leads in FirstPromoter
        so when a person referred by the promoter/affiliate signs up, a new referral
        should be added inside FirstPromoter **(you can see them inside the `Referrals`
        section as `Leads`)**. <br/><br/><Tip>The recommended way to do this is to
        grab the `_fprom_tid` **(_fprom_track for accounts created prior to April
        2021)** cookie value(which keeps the tracking id and referral identification)
        on your server and send it along with the sign-up data through the tid parameter.
        <br/><br/> **Alternative:** In some special cases, you can refer sign ups
        directly to a promoter, by passing the referral id through ref_id parameter.
        Be careful when using this because the referral id can be modified by the
        promoter by default, however you can disable that from the campaign configuration
        page.</Tip><Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/track/signup`</Tip>
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: Email of the lead/sign-up. Required if uid is not provided.
                uid:
                  type: string
                  description: ID to match the sale with the lead if the email can
                    be changed before the first sale. Required if email is not provided.
                tid:
                  type: string
                  description: Visitor tracking ID. It's set when the visitor tracking
                    script tracks the referral visit on our system. The value is found
                    inside _fprom_tid cookie. Required if ref_id is not provided.
                ref_id:
                  type: string
                  description: Default referral id of the promoter. Use this only
                    when you want to assign the lead to a specific promoter. Required
                    if tid is not provided.
                ip:
                  type: string
                  description: IP of the visitor who generated the sign up. It's used
                    for fraud analysis.
                created_at:
                  type: string
                  description: ISO date string of the date of the signup event
                skip_email_notification:
                  type: boolean
                  description: Set this to true to skip email notifications. Default
                    is false.
              oneOf:
              - required:
                - email
              - required:
                - uid
      parameters:
      - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Successful signup response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 45831611
                  etype:
                    type: string
                    example: signup
                  sale_amount:
                    type: integer
                    nullable: true
                    example: null
                  original_sale_amount:
                    type: integer
                    nullable: true
                    example: null
                  original_sale_currency:
                    type: string
                    nullable: true
                    example: null
                  event_id:
                    type: string
                    nullable: true
                    example: null
                  plan_id:
                    type: string
                    nullable: true
                    example: null
                  billing_period:
                    type: string
                    nullable: true
                    example: null
                  created_at:
                    type: string
                    format: date-time
                    example: '2025-04-25T09:29:51.973Z'
                  referral:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 29203686
                      email:
                        type: string
                        example: testme@test1.com
                      uid:
                        type: string
                        nullable: true
                        example: null
                  commissions:
                    type: array
                    items: {}
                    example: []
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Error. Email and uid can not be blank!
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Visitor  invalid, not found or you are trying to use
                      the signup tracking test via API which doesn't work on API calls.
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  transaction_id:
                    type: string
                    example: there is already a signup event registered on this lead
  /track/sale:
    post:
      description: Assign sales and commissions to your promoters. To track sales
        and generate commissions correctly, you need to use this API call each time
        a non-zero amount sale is processed in your system, even if it comes from
        a recurring charge or one-time charge. <Note>To avoid fraudulent sales, we
        don't use JS conversion pixels to track sales, which are very unreliable and
        can be easily faked. Instead, we use server-side tracking for all sales to
        ensure that a sale is tracked only when you actually receive money in your
        billing account.  <br/><br/>To maintain the same standards with the API, we
        recommend making the sale API call (this call) only when you receive confirmation
        of the sale from your billing provider, such as from a webhook, an IPN, or
        a success response from an API charge call.<br/><br/>You just need to pass
        the sale amount (before taxes) and we'll take care of the rest. The commissions/rewards
        will be calculated based on that amount and the plan ID, in case you use the
        plan-level rewards feature.</Note> Using email or UID parameters, we identify
        the lead/customer who generated the sale, which also helps us determine the
        promoter who owns the reward/commission. <br/><br/>The lead is added to our
        system either by the client signup tracking script when the user signs up
        or by calling the signup API endpoint. There is also the option to bypass
        the signup tracking by using TID or ref_id parameters, which will create the
        lead and assign the sale in one go.<br/><br/>**If we don't find the lead in
        our system, then it means that the sale is not a referral sale, you'll get
        a 404 response. Also, if the promoter is banned, you'll get a 404 response.
        You don't have to identify which sale is from referrals and which is not;
        we'll take care of that.** <Tip>**For zero-decimal** currencies like `JPY`,
        `amount` and `mrr` parameters should be sent as **whole values**. <br/><br/>**For
        other currencies**, `amount` and `mrr` parameter values should be in cents,
        i.e., you will need to **multiply the value by 100** before sending the request.</Tip><Tip>**HTTP
        Request** <br/>`POST https://api.firstpromoter.com/api/v2/track/sale`</Tip>
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - event_id
              - amount
              properties:
                email:
                  type: string
                  description: Email of the lead/sign-up. Required if uid is not provided.
                uid:
                  type: string
                  description: uid of the lead added on signup tracking. Required
                    if email is not provided.
                event_id:
                  type: string
                  description: Transaction or sale event ID. Required to avoid duplicate
                    sales.
                amount:
                  type: integer
                  description: The sale amount in cents. For zero-decimal currencies
                    like JPY, amount should be whole values.
                quantity:
                  type: integer
                  description: Number of subscriptions/items. Optional if quantity
                    is 1.
                plan:
                  type: string
                  description: Customer plan ID from billing provider. Used for plan-level
                    rewards.
                currency:
                  type: string
                  description: Required only if different from FirstPromoter settings
                    default currency.
                mrr:
                  type: string
                  description: Monthly Recurring Revenue generated by the customer.
                promo_code:
                  type: string
                  description: For promo code tracking.
                tid:
                  type: string
                  description: Visitor tracking ID from _fprom_tid cookie.
                ref_id:
                  type: string
                  description: Referral ID of the promoter.
                skip_email_notification:
                  type: boolean
                  description: Set true to skip email notifications. Default is false.
              oneOf:
              - required:
                - email
              - required:
                - uid
      responses:
        '200':
          description: Sale tracked successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 45831949
                  etype:
                    type: string
                    example: sale
                  sale_amount:
                    type: integer
                    example: 2000
                  original_sale_amount:
                    type: integer
                    example: 2000
                  original_sale_currency:
                    type: string
                    nullable: true
                    example: null
                  event_id:
                    type: string
                    nullable: true
                    example: null
                  plan_id:
                    type: string
                    nullable: true
                    example: null
                  billing_period:
                    type: string
                    nullable: true
                    example: null
                  created_at:
                    type: string
                    format: date-time
                    example: '2025-04-25T09:39:42.289Z'
                  referral:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 29203686
                      email:
                        type: string
                        example: testme@test1.com
                      uid:
                        type: string
                        nullable: true
                        example: null
                  commissions:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 13533003
                        status:
                          type: string
                          example: approved
                        metadata:
                          type: object
                          example: {}
                        is_self_referral:
                          type: boolean
                          example: false
                        commission_type:
                          type: string
                          example: sale
                        created_by_user_email:
                          type: string
                          nullable: true
                          example: null
                        created_by_user_at:
                          type: string
                          nullable: true
                          example: null
                        sale_amount:
                          type: integer
                          example: 2000
                        original_sale_amount:
                          type: integer
                          example: 2000
                        original_sale_currency:
                          type: string
                          nullable: true
                          example: null
                        event_id:
                          type: string
                          nullable: true
                          example: null
                        plan_id:
                          type: string
                          nullable: true
                          example: null
                        tier:
                          type: integer
                          example: 1
                        internal_note:
                          type: string
                          nullable: true
                          example: null
                        external_note:
                          type: string
                          nullable: true
                          example: null
                        unit:
                          type: string
                          example: cash
                        fraud_check:
                          type: string
                          example: no_suspicion
                        amount:
                          type: integer
                          example: 400
                        is_paid:
                          type: boolean
                          example: false
                        is_split:
                          type: boolean
                          example: false
                        created_at:
                          type: string
                          format: date-time
                          example: '2025-04-25T09:39:42Z'
                        status_updated_at:
                          type: string
                          nullable: true
                          example: null
                        promoter_campaign:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 14850130
                            campaign_id:
                              type: integer
                              example: 28004
                            promoter_id:
                              type: integer
                              example: 8262622
                            created_at:
                              type: string
                              format: date-time
                              example: '2025-01-16T18:16:41Z'
                            promoter:
                              type: object
                              properties:
                                id:
                                  type: integer
                                  example: 8262622
                                email:
                                  type: string
                                  example: test@promoter.com
                                name:
                                  type: string
                                  example: Test Promoter
                            campaign:
                              type: object
                              properties:
                                id:
                                  type: integer
                                  example: 28004
                                name:
                                  type: string
                                  example: Quinn Ramirez
                                color:
                                  type: string
                                  example: '#EC4899'
                        referral:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 29203686
                            email:
                              type: string
                              example: testme@test1.com
                            uid:
                              type: string
                              nullable: true
                              example: null
                        reward:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 157427
                            name:
                              type: string
                              example: 20% recurring commission
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Referral corresponding to email or uid parameter not
                      found or promoter is banned.
                  code:
                    type: string
                    example: not_found
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Error. Amount blank or invalid.
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The 'sale' event with the id 'test_sale_12340987' already
                      exists.
  /track/refund:
    post:
      description: The refund call is similar to the sale call. It works the same
        way, except that it generates negative commissions. <Tip>**HTTP Request**
        <br/>`POST https://api.firstpromoter.com/api/v2/track/refund`</Tip>
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - event_id
              - amount
              properties:
                email:
                  type: string
                  description: Email of the lead/sign-up. Required if uid is not provided.
                uid:
                  type: string
                  description: uid of the lead added on signup tracking. Required
                    if email is not provided.
                event_id:
                  type: string
                  description: Transaction or refund event ID. Required to avoid generating
                    duplicate refunds.
                amount:
                  type: string
                  description: The refund amount in cents. Used to calculate negative
                    commissions/rewards.
                currency:
                  type: string
                  description: This field is only required if the currency of the
                    sale/refund is not the same as the one set on FirstPromoter settings.
                    We'll automatically convert the amount from this currency to the
                    default one set on your FirstPromoter account.
                quantity:
                  type: string
                  description: Number of subscriptions/items refunded. Optional if
                    quantity is 1.
                sale_event_id:
                  type: string
                  description: The event id of the sale for which the refund is processed.
                    Should match the event_id from the sales tracking API call. Required
                    for accurate tracking of multiple products or changing commission
                    levels.
                skip_email_notification:
                  type: boolean
                  description: Set true to skip email notifications. Default is false.
              oneOf:
              - required:
                - email
              - required:
                - uid
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 33847726
                  type:
                    type: string
                    example: refund
                  amount_cents:
                    type: integer
                    example: -1000
                  reward:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 10940148
                      status:
                        type: string
                        example: approved
                      amount:
                        type: integer
                        example: -200
                      unit:
                        type: string
                        example: cash
                      created_at:
                        type: string
                        format: date-time
                        example: '2024-09-11T14:36:01.016Z'
                      lead:
                        $ref: '#/components/schemas/Lead'
                      event_id:
                        type: string
                        example: test_sale_12340987_refund
                      conversion_amount:
                        type: integer
                        example: -1000
                      tier_level:
                        type: integer
                        example: 1
                      split_type:
                        type: string
                        nullable: true
                        example: null
                  lead:
                    $ref: '#/components/schemas/Lead'
                  promoter:
                    $ref: '#/components/schemas/Promoter'
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Error. Amount blank or invalid.
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The 'refund' event with the id 'test_sale_12340987_refund'
                      already exists.
  /track/cancellation:
    post:
      description: This call will mark the customer as cancelled and will decrease
        the MRR generated by them. <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/track/cancellation`</Tip>
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: Email of the lead/sign-up. Required if uid is not provided.
                uid:
                  type: string
                  description: uid of the lead added on signup tracking. Required
                    if email is not provided.
              oneOf:
              - required:
                - email
              - required:
                - uid
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 33848911
                  type:
                    type: string
                    example: cancellation
                  amount_cents:
                    type: integer
                    nullable: true
                    example: null
                  reward:
                    type: object
                    nullable: true
                    example: null
                  lead:
                    $ref: '#/components/schemas/Lead'
                  promoter:
                    $ref: '#/components/schemas/Promoter'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Error. Email and uid can not be blank!
  /company/webhooks:
    get:
      summary: List webhook subscriptions
      tags:
      - Webhooks
      description: "Returns a paginated list of all webhook subscriptions for your\
        \ account, ordered by creation date descending. \n <Tip>**HTTP Request** <br/>`GET\
        \ https://api.firstpromoter.com/api/v2/company/webhooks`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: per_page
        in: query
        schema:
          type: integer
          default: 25
        description: Number of results per page.
      - name: page
        in: query
        schema:
          type: integer
          default: 1
        description: Page number.
      responses:
        '200':
          description: Paginated list of webhook subscriptions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebhookSubscription'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    post:
      summary: Create a webhook subscription
      tags:
      - Webhooks
      description: "Creates a new webhook subscription. The `secret_key` is auto-generated\
        \ and returned only in this response — store it immediately. \n <Tip>**HTTP\
        \ Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/webhooks`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSubscriptionInput'
      responses:
        '201':
          description: Subscription created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/webhooks/event_types:
    get:
      summary: List supported event types
      tags:
      - Webhooks
      description: "Returns a sorted list of all event type strings that can be subscribed\
        \ to. Use these values in the `event_types` array when creating or updating\
        \ a subscription. \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/webhooks/event_types`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: List of supported event types
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: string
                    example:
                    - commission.created
                    - commission.deleted
                    - commission.updated
                    - contract_document.signed
                    - payments_batch.created
                    - payments_batch.deleted
                    - payments_batch.updated
                    - payout.commissions.created
                    - payout.commissions.deleted
                    - payout.commissions.updated
                    - payout.created
                    - payout.deleted
                    - payout.updated
                    - payout_method.created
                    - payout_method.deleted
                    - payout_method.updated
                    - promoter.balance.updated
                    - promoter.created
                    - promoter.deleted
                    - promoter.profile.updated
                    - promoter.updated
                    - promoter_campaign.created
                    - promoter_campaign.deleted
                    - promoter_campaign.updated
                    - referral.created
                    - referral.deleted
                    - referral.moved
                    - referral.updated
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /company/webhooks/test:
    post:
      summary: Send a test webhook delivery
      tags:
      - Webhooks
      description: "Sends a sample payload for the given event type to the specified\
        \ URL immediately. Useful for verifying that your endpoint is reachable and\
        \ processing payloads correctly before creating a subscription. \n\n The signature\
        \ in the test request is generated with a random secret (not a saved subscription's\
        \ secret), so signature verification will fail — this is expected during testing.\
        \ \n\n Returns the HTTP status and body received from your endpoint. \n <Tip>**HTTP\
        \ Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/webhooks/test`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              - event_type
              properties:
                url:
                  type: string
                  format: uri
                  description: The URL to send the test payload to. Must be a public
                    URL — requests to private/internal networks are blocked.
                event_type:
                  type: string
                  description: The event type to generate a sample payload for. Use
                    any value from the `event_types` endpoint.
                basic_auth_user:
                  type: string
                  description: HTTP Basic Auth username to include in the test request.
                basic_auth_password:
                  type: string
                  description: HTTP Basic Auth password to include in the test request.
                headers:
                  type: object
                  description: Custom HTTP headers to include in the test request.
                  additionalProperties:
                    type: string
                  example:
                    X-Api-Key: my-secret-token
      responses:
        '200':
          description: Test delivery sent — response mirrors what your endpoint returned.
        '400':
          description: Invalid URL (private network or malformed URI)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /company/webhooks/{id}:
    get:
      summary: Get a webhook subscription
      tags:
      - Webhooks
      description: "Returns the details of a single webhook subscription. \n <Tip>**HTTP\
        \ Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/webhooks/{id}`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: ID of the webhook subscription.
      responses:
        '200':
          description: Webhook subscription details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
    put:
      summary: Update a webhook subscription
      tags:
      - Webhooks
      description: "Updates an existing webhook subscription. Only fields you include\
        \ in the request body are changed. \n <Tip>**HTTP Request** <br/>`PUT https://api.firstpromoter.com/api/v2/company/webhooks/{id}`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: ID of the webhook subscription.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSubscriptionInput'
      responses:
        '200':
          description: Subscription updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete a webhook subscription
      tags:
      - Webhooks
      description: "Permanently deletes a webhook subscription and all its delivery\
        \ records. \n <Tip>**HTTP Request** <br/>`DELETE https://api.firstpromoter.com/api/v2/company/webhooks/{id}`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: ID of the webhook subscription.
      responses:
        '200':
          description: Subscription deleted successfully
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
  /company/webhooks/{webhook_id}/webhook_deliveries:
    get:
      summary: List deliveries for a subscription
      tags:
      - Webhook Deliveries
      description: "Returns a paginated list of delivery attempts for the given subscription,\
        \ ordered most-recent first. \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/webhooks/{webhook_id}/webhook_deliveries`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: webhook_id
        in: path
        required: true
        schema:
          type: integer
        description: ID of the webhook subscription.
      - name: per_page
        in: query
        schema:
          type: integer
          default: 25
        description: Number of results per page.
      - name: page
        in: query
        schema:
          type: integer
          default: 1
        description: Page number.
      responses:
        '200':
          description: Paginated list of webhook deliveries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebhookDelivery'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Subscription not found
  /company/webhooks/{webhook_id}/webhook_deliveries/{id}:
    get:
      summary: Get a delivery
      tags:
      - Webhook Deliveries
      description: "Returns the full details of a single delivery attempt, including\
        \ the complete payload that was sent and the response received from your endpoint.\
        \ \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/webhooks/{webhook_id}/webhook_deliveries/{id}`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: webhook_id
        in: path
        required: true
        schema:
          type: integer
        description: ID of the webhook subscription.
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: ID of the delivery.
      responses:
        '200':
          description: Webhook delivery details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDelivery'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
  /company/webhooks/{webhook_id}/webhook_deliveries/{id}/retry_delivery:
    post:
      summary: Retry a failed delivery
      tags:
      - Webhook Deliveries
      description: "Re-queues a failed delivery for immediate retry. The delivery's\
        \ `status` is reset to `pending` and `attempts` is reset to `0`. \n\n Returns\
        \ `422` if the subscription's `max_retries` limit has already been reached.\
        \ \n <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/webhooks/{webhook_id}/webhook_deliveries/{id}/retry_delivery`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: webhook_id
        in: path
        required: true
        schema:
          type: integer
        description: ID of the webhook subscription.
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: ID of the delivery to retry.
      responses:
        '200':
          description: Delivery re-queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDelivery'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '422':
          description: Max retries already reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token
  schemas:
    BatchProcess:
      type: object
      properties:
        id:
          type: integer
          example: 8
        status:
          type: string
          enum:
          - pending
          - in_progress
          - completed
          - failed
          - stopped
          example: stopped
        total:
          type: integer
          example: 5
        selected_total:
          type: integer
          example: 5
        processed_count:
          type: integer
          example: 0
        failed_count:
          type: integer
          example: 0
        action_label:
          type: string
          example: referral/delete
        created_at:
          type: string
          format: date-time
          example: '2025-03-26T15:15:34.908Z'
        updated_at:
          type: string
          format: date-time
          example: '2025-03-26T15:15:34.908Z'
        meta:
          type: object
          nullable: true
        progress:
          type: integer
          example: 0
        processing_errors:
          type: array
          items:
            type: string
          example: []
    Error:
      type: object
      properties:
        message:
          type: string
          example: Invalid user type
        code:
          type: string
          example: forbidden
    BatchOperationResponse:
      type: object
      properties:
        id:
          type: integer
          description: Batch ID
        status:
          type: string
          enum:
          - completed
          - pending
          - in_progress
          - failed
          - stopped
          description: Status of the batch operation
        total:
          type: integer
          description: Total number of items
        selected_total:
          type: integer
          description: Total 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: Label for the action
        created_at:
          type: string
          format: date-time
          description: Creation date of the batch operation
        updated_at:
          type: string
          format: date-time
          description: Last update date of the batch operation
        meta:
          type: object
          description: Additional metadata
        progress:
          type: integer
          description: Progress of the batch operation
        processing_errors:
          type: array
          items:
            type: string
          description: List of processing errors if any
    CommissionFilters:
      type: object
      properties:
        status:
          type: string
          enum:
          - pending
          - approved
          - denied
        paid:
          type: string
          enum:
          - 'yes'
          - 'no'
          description: Paid filter for monetary commissions
        fulfilled:
          type: string
          enum:
          - 'yes'
          - 'no'
          description: Fulfilled filter for non-monetary commissions
        sale_amount:
          type: object
          properties:
            from:
              type: integer
              description: Sale amount from
            to:
              type: integer
              description: Sale amount to
        amount:
          type: object
          properties:
            from:
              type: integer
              description: Amount from
            to:
              type: integer
              description: Amount to
        created_at:
          type: object
          properties:
            from:
              type: string
              format: date
              description: created_at start date
            to:
              type: string
              format: date
              description: created_at end date
        campaign_id:
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
          description: Campaign ids. Can be Integer or Array of Integers
        payout_id:
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
          description: Payout ids. Can be Integer or Array of Integers
        due_period:
          type: string
          enum:
          - next
          - overdue
          - custom
          description: Due period filter
        promoter_id:
          type: integer
          description: Promoter id
        first_commission:
          type: boolean
          description: First commission
        refunded:
          type: boolean
          description: Refunded reward
        fraud_check:
          type: string
          enum:
          - no_suspicion
          - same_ip_suspicion
          - same_promoter_email
          - ad_source
          description: Referral fraud check (suspicion). Array accepted
        plan_id:
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
          description: Plan id
    CommissionSorting:
      type: object
      properties:
        sale_amount:
          type: string
          enum:
          - asc
          - desc
          description: The sort by sale direction
        amount:
          type: string
          enum:
          - asc
          - desc
          description: The sort by amount direction
        created_at:
          type: string
          enum:
          - asc
          - desc
          description: The sort by created_at direction
        referral:
          type: string
          enum:
          - asc
          - desc
          description: The sort by referral direction
    CommissionCreate:
      oneOf:
      - title: Sale Commission
        type: object
        required:
        - commission_type
        - referral_id
        - sale_amount
        properties:
          commission_type:
            type: string
            enum:
            - sale
            description: The commission type
          referral_id:
            type: integer
            description: Referral id. Required for sale commission type.
          plan_id:
            type: integer
            description: One of the items id from price_ids
          sale_amount:
            type: integer
            description: Sale amount in cents. Required for sale commission type.
          event_id:
            type: string
            description: The ID of the event that generated the sale from billing
              provider
          event_date:
            type: string
            format: date
            description: The date of the event that generated the sale
          internal_note:
            type: string
            description: Internal note visible only by the team
          unit:
            type: string
            enum:
            - cash
            - credits
            - points
            - free_months
            - mon_discount
            - discount_per
            description: Set the reward unit type
          notify_promoter:
            type: boolean
            description: If true a notification email is sent to promoter if enabled
              on Emails section
          billing_period:
            type: string
            enum:
            - monthly
            - yearly
            - one_time
            description: The billing period of the event that generated the sale
      - title: Custom Commission
        type: object
        required:
        - commission_type
        - promoter_campaign_id
        - amount
        properties:
          commission_type:
            type: string
            enum:
            - custom
            description: The commission type
          promoter_campaign_id:
            type: integer
            description: PromoterCampaign id. Required for custom commission type.
              This ID is not the promoter’s ID or the campaign’s ID. It’s the linking
              record that defines the promoter’s participation in that campaign. You
              can find this id in each object in the promoter_campaigns array when
              you get the details of the promoter.
          amount:
            type: integer
            description: Commission amount in cents. Required for custom commission
              type.
          event_id:
            type: string
            description: The ID of the event that generated the sale from billing
              provider
          event_date:
            type: string
            format: date
            description: The date of the event that generated the sale
          internal_note:
            type: string
            description: Internal note visible only by the team
          unit:
            type: string
            enum:
            - cash
            - credits
            - points
            - free_months
            - mon_discount
            - discount_per
            description: Set the reward unit type
          notify_promoter:
            type: boolean
            description: If true a notification email is sent to promoter if enabled
              on Emails section
          billing_period:
            type: string
            enum:
            - monthly
            - yearly
            - one_time
            description: The billing period of the event that generated the sale
      discriminator:
        propertyName: commission_type
        mapping:
          sale: '#/components/schemas/CommissionCreate/oneOf/0'
          custom: '#/components/schemas/CommissionCreate/oneOf/1'
    CommissionUpdate:
      type: object
      properties:
        internal_note:
          type: string
          description: Internal note visible only by the team
        external_note:
          type: string
          description: External note visible by the promoter
    BatchActionRequest:
      type: object
      properties:
        ids:
          type: array
          items:
            type: integer
          description: Array of commission 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`
    PayoutResponse:
      type: object
      properties:
        id:
          type: integer
          description: Operation ID
        status:
          type: string
          description: Status of the operation
          example: completed
        total:
          type: integer
          description: Total number of commissions
        selected_total:
          type: integer
          description: Number of selected commissions
        processed_count:
          type: integer
          description: Number of processed commissions
        failed_count:
          type: integer
          description: Number of failed operations
        action_label:
          type: string
          description: Action identifier
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
        meta:
          type: object
          description: Additional metadata
        progress:
          type: number
          description: Progress indicator (0-1)
        processing_errors:
          type: array
          description: List of processing errors
          items:
            type: string
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
        code:
          type: string
          description: Error code
    Commission:
      type: object
      properties:
        id:
          type: integer
          description: Commission ID
        status:
          type: string
          enum:
          - pending
          - approved
          - denied
          description: Current status of the commission
        metadata:
          type: object
          description: Additional metadata about the commission
        is_self_referral:
          type: boolean
          nullable: true
          description: Whether this is a self-referral
        commission_type:
          type: string
          enum:
          - sale
          - custom
          description: Type of commission
        created_by_user_email:
          type: string
          nullable: true
          description: Email of the user who created the commission
        created_by_user_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the user created the commission
        sale_amount:
          type: integer
          description: Amount of the sale
        original_sale_amount:
          type: integer
          description: Original amount of the sale
        original_sale_currency:
          type: string
          nullable: true
          description: Currency of the original sale
        event_id:
          type: string
          nullable: true
          description: ID of the event that generated the commission
        plan_id:
          type: string
          nullable: true
          description: Plan ID associated with the commission
        tier:
          type: integer
          description: Reward tier
        internal_note:
          type: string
          nullable: true
          description: Internal note visible only to the team
        external_note:
          type: string
          nullable: true
          description: External note visible to the promoter
        unit:
          type: string
          enum:
          - cash
          - credits
          - points
          - free_months
          - mon_discount
          - discount_per
          description: Unit type for the reward
        fraud_check:
          type: string
          nullable: true
          enum:
          - no_suspicion
          - same_ip_suspicion
          - same_promoter_email
          - ad_source
          description: Result of fraud check
        amount:
          type: integer
          description: Commission amount
        is_paid:
          type: boolean
          description: Whether the commission has been paid
        is_split:
          type: boolean
          description: Whether the commission is split among multiple promoters
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        status_updated_at:
          type: string
          format: date-time
          nullable: true
          description: Last status update timestamp
        promoter_campaign:
          type: object
          properties:
            id:
              type: integer
              description: Promoter campaign ID
            campaign_id:
              type: integer
              description: Campaign ID
            promoter_id:
              type: integer
              description: Promoter ID
            created_at:
              type: string
              format: date-time
              description: Creation timestamp
            promoter:
              type: object
              properties:
                id:
                  type: integer
                  description: Promoter ID
                email:
                  type: string
                  description: Promoter email
                name:
                  type: string
                  description: Promoter name
            campaign:
              type: object
              properties:
                id:
                  type: integer
                  description: Campaign ID
                name:
                  type: string
                  description: Campaign name
                color:
                  type: string
                  nullable: true
                  description: Campaign color
        referral:
          type: object
          nullable: true
          properties:
            id:
              type: integer
              description: Referral ID
            email:
              type: string
              description: Referral email
            uid:
              type: string
              description: Referral UID
        reward:
          type: object
          properties:
            id:
              type: integer
              description: Reward ID
            name:
              type: string
              description: Reward name
        split_details:
          type: object
          nullable: true
          description: Commission split details from the associated referral, when
            the referral is shared between promoters
    EmailRequest:
      type: object
      required:
      - name
      - subject
      - content
      - allowed_campaign_ids
      - trigger
      properties:
        name:
          type: string
          description: Name of the email
        subject:
          type: string
          description: Subject of the email
        content:
          type: string
          description: Content of the email
        allowed_campaign_ids:
          type: array
          description: Array of allowed campaign ids
        trigger:
          type: object
          required:
          - enabled
          - trigger_on
          - settings
          properties:
            enabled:
              type: boolean
              description: Flag to enable trigger
            trigger_on:
              type: string
              enum:
              - promoter_accepted
              - promoter_rejected
              - reward_created
              - fulfilment_completed
              - count_reached
              - lead_signup
              - inactivity
              - broadcast
              - recurring
              description: Trigger on
            settings:
              type: object
              properties:
                delay_interval:
                  type: string
                  enum:
                  - second
                  - minute
                  - hour
                  - day
                  description: Delay interval is required when trigger_on is 'promoter_accepted'
                delay_value:
                  type: integer
                  description: Delay value is required when trigger_on is 'promoter_accepted'
                count:
                  type: integer
                  description: Count is required when trigger_on is 'count_reached'
                metric:
                  type: string
                  enum:
                  - clicks
                  - referrals
                  - customers
                  - cancellations
                  description: Metric is required when trigger_on is 'count_reached'
                    or 'inactivity'
                period_in_days:
                  type: integer
                  description: Period in days is required when trigger_on is 'inactivity'
                frequency:
                  type: string
                  enum:
                  - weekly
                  - monthly
                  description: Required for recurring trigger_on
                day:
                  type: integer
                  description: Required for recurring trigger_on. When frequency ==
                    weekly -> From 0(Sunday) to 6(Saturday). When frequency == montlhy
                    -> From 1 to 31.
                hour:
                  type: integer
                  minimum: 0
                  maximum: 23
                  description: Required for recurring trigger_on
                minute:
                  type: integer
                  minimum: 0
                  maximum: 59
                  description: Required for recurring trigger_on
    Payout:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the payout
        status:
          type: string
          enum:
          - pending
          - completed
          - failed
          - processing
          - cancelled
          description: Status of the payout
        amount:
          type: number
          format: float
          description: Amount of the payout
        payments_batch_id:
          type: integer
          description: ID of the payments batch
        tax_rate:
          type: number
          format: float
          description: Tax rate applied to the payout
        unit:
          type: string
          description: Unit of the payout (e.g., cash)
        period_start:
          type: string
          format: date-time
          description: Start date of the period
        period_end:
          type: string
          format: date-time
          description: End date of the period
        paid_at:
          type: string
          format: date-time
          description: Date when the payout was paid
        processing_started_at:
          type: string
          format: date-time
          description: Date when the payout processing started
        failed_at:
          type: string
          format: date-time
          description: Date when the payout failed
        error:
          type: string
          description: Error message if the payout failed
        total_incl_tax:
          type: number
          format: float
          description: Total amount including tax
        created_at:
          type: string
          format: date-time
          description: Date when the payout was created
        payout_method:
          type: object
          properties:
            id:
              type: integer
              description: ID of the payout method
            method:
              type: string
              description: Payout method name
            date_added:
              type: string
              format: date-time
              description: Date when the payout method was added
            is_disabled:
              type: boolean
              description: Whether the payout method is disabled
            meta:
              type: object
              description: Additional meta information
            is_selected:
              type: boolean
              description: Whether the payout method is selected
            details:
              type: object
              description: Details about the payout method
            managed_payouts:
              type: boolean
              description: Whether payouts are managed by us (auto-payouts)
        promoter:
          type: object
          properties:
            id:
              type: integer
              description: ID of the promoter
            email:
              type: string
              description: Email 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
              description: Color of the campaign
    PayoutStats:
      type: object
      properties:
        meta:
          type: object
          properties:
            net_payout_days:
              type: integer
              description: Number of days for net payout
            payout_cycle:
              type: string
              description: Payout cycle (e.g., monthly)
            min_payment:
              type: integer
              description: Minimum payment amount
            min_paying_customers:
              type: integer
              description: Minimum number of paying customers
            terms_description:
              type: string
              description: Description of payment terms
            selected_payout_methods:
              type: array
              items:
                type: string
              description: List of selected payout methods
            payout_method_options:
              type: object
              description: Options for payout methods
            managed_payouts:
              type: boolean
              description: Whether payouts are managed by us (auto-payouts)
        data:
          type: object
          properties:
            by_paid_period:
              type: array
              items:
                type: object
                properties:
                  period_start:
                    type: string
                    format: date-time
                    description: Start date of the period
                  period_end:
                    type: string
                    format: date-time
                    description: End date of the period
                  promoters_count:
                    type: integer
                    description: Count of promoters
                  amounts:
                    type: object
                    additionalProperties:
                      type: number
                    description: Amounts by currency or unit
                  total_incl_tax:
                    type: number
                    description: Total amount including tax
            by_status:
              type: object
              additionalProperties:
                type: object
                properties:
                  amounts:
                    type: object
                    additionalProperties:
                      type: number
                  total_incl_tax:
                    type: number
                  promoters_count:
                    type: integer
            by_payout_method:
              type: object
              additionalProperties:
                type: object
                properties:
                  amounts:
                    type: object
                    additionalProperties:
                      type: number
                  total_incl_tax:
                    type: number
                  promoters_count:
                    type: integer
    PayoutDueStats:
      type: object
      properties:
        meta:
          type: object
          properties:
            net_payout_days:
              type: integer
              description: Number of days for net payout
            payout_cycle:
              type: string
              description: Payout cycle (e.g., monthly)
            min_payment:
              type: integer
              description: Minimum payment amount
            min_paying_customers:
              type: integer
              description: Minimum number of paying customers
            terms_description:
              type: string
              description: Description of payment terms
            selected_payout_methods:
              type: array
              items:
                type: string
              description: List of selected payout methods
            payout_method_options:
              type: object
              description: Options for payout methods
            managed_payouts:
              type: boolean
              description: Whether payouts are managed by us (auto-payouts)
        data:
          type: object
          properties:
            next:
              type: object
              properties:
                promoters_count:
                  type: integer
                  description: Count of promoters
                amounts:
                  type: object
                  additionalProperties:
                    type: number
                  description: Amounts by currency or unit
                total_incl_tax:
                  type: number
                  description: Total amount including tax
                due_date:
                  type: string
                  format: date
                  description: Due date for the next payout
                period_end:
                  type: string
                  format: date
                  description: End date of the period
            overdue:
              type: object
              properties:
                promoters_count:
                  type: integer
                  description: Count of promoters
                amounts:
                  type: object
                  additionalProperties:
                    type: number
                  description: Amounts by currency or unit
                total_incl_tax:
                  type: number
                  description: Total amount including tax
                due_date:
                  type: string
                  format: date
                  description: Due date for overdue payout
                period_end:
                  type: string
                  format: date
                  description: End date of the period
            custom:
              type: object
              properties:
                promoters_count:
                  type: integer
                  description: Count of promoters
                amounts:
                  type: object
                  additionalProperties:
                    type: number
                  description: Amounts by currency or unit
                total_incl_tax:
                  type: number
                  description: Total amount including tax
    PayoutsGroupedByPromoters:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              promoter:
                type: object
                properties:
                  id:
                    type: integer
                    description: ID of the promoter
                  email:
                    type: string
                    description: Email of the promoter
                  name:
                    type: string
                    description: Name of the promoter
                  invoice_details_status:
                    type: string
                    description: Status of invoice details
                  fraud_suspicions:
                    type: array
                    items:
                      type: string
                    description: List of fraud suspicions
                  profile:
                    type: object
                    properties:
                      invoice_details_validation_errors:
                        type: object
                        description: Validation errors for invoice details
              payout_method:
                type: object
                properties:
                  id:
                    type: integer
                    description: ID of the payout method
                  method:
                    type: string
                    description: Payout method name
                  date_added:
                    type: string
                    format: date-time
                    description: Date when the payout method was added
                  is_disabled:
                    type: boolean
                    description: Whether the payout method is disabled
                  meta:
                    type: object
                    description: Additional meta information
                  is_selected:
                    type: boolean
                    description: Whether the payout method is selected
                  details:
                    type: object
                    description: Details about the payout method
                  managed_payouts:
                    type: boolean
                    description: Whether payouts are managed by us (auto-payouts)
              payouts:
                type: array
                items:
                  $ref: '#/components/schemas/Payout'
              is_amount_payable:
                type: boolean
                description: Whether the amount is payable
              payout_ids:
                type: array
                items:
                  type: integer
                description: List of payout IDs
              amount:
                type: number
                description: Total amount
              total_incl_tax:
                type: number
                description: Total amount including tax
        meta:
          type: object
          properties:
            total:
              type: number
              description: Total amount
            promoters_count:
              type: integer
              description: Count of promoters
            total_incl_tax:
              type: number
              description: Total amount including tax
            due_date:
              type: string
              format: date
              description: Due date
            period_end:
              type: string
              format: date
              description: End date of the period
    PaymentsBatch:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: integer
              description: ID of the payments batch
            status:
              type: string
              enum:
              - awaiting_confirmation
              - pending
              - processing
              - completed
              - failed
              description: Status of the payments batch
            ext_reference:
              type: string
              description: External reference
            ext_id:
              type: string
              description: External ID
            scheduled_at:
              type: string
              format: date-time
              description: When the batch is scheduled
            processing_started_at:
              type: string
              format: date-time
              description: When processing started
            completed_at:
              type: string
              format: date-time
              description: When the batch was completed
            is_payable:
              type: boolean
              description: Whether the batch is payable
            is_retriable:
              type: boolean
              description: Whether the batch can be retried
            is_payment_otp_required:
              type: boolean
              description: Whether OTP is required for payment
            total:
              type: number
              description: Total amount
            promoters_count:
              type: integer
              description: Count of promoters
            error:
              type: string
              description: Error message if the batch failed
        meta:
          type: object
          properties:
            failed:
              type: array
              items:
                type: object
              description: List of failed items
    BatchActionResult:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: integer
              description: ID of the batch action
            status:
              type: string
              enum:
              - pending
              - completed
              - failed
              description: Status of the batch action
            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 items
            action_label:
              type: string
              description: Label of the action
            created_at:
              type: string
              format: date-time
              description: When the action was created
            updated_at:
              type: string
              format: date-time
              description: When the action was last updated
            meta:
              type: object
              description: Meta information about the action
            progress:
              type: integer
              description: Progress of the action (0-100)
            processing_errors:
              type: array
              items:
                type: object
              description: List of processing errors
        meta:
          type: object
          properties:
            total:
              type: number
              description: Total amount
            promoters_count:
              type: integer
              description: Count of promoters
            total_incl_tax:
              type: number
              description: Total amount including tax
            all_promoters_count:
              type: integer
              description: Count of all promoters
    Ids:
      type: array
      items:
        type: integer
      description: Array of Payout IDs
    PromoCode:
      type: object
      properties:
        id:
          type: integer
          description: ID of the promo code entry
        code:
          type: string
          description: Code of the promo code
        reward:
          type: object
          properties:
            id:
              type: integer
              description: ID of the reward
            name:
              type: string
              description: Name of the reward
          description: Reward
        ext_id:
          type: string
        description:
          type: string
          description: Description of the promo code
        company_id:
          type: integer
        promoter_campaign_id:
          type: integer
          description: ID of the promoter campaign
        metadata:
          type: object
          description: Metadata of the promo code
        details:
          type: object
          description: Details of the promo code
        archived_at:
          type: string
          format: date-time
    PromoterCampaign:
      type: object
      properties:
        id:
          type: integer
        campaign_id:
          type: integer
        promoter_id:
          type: integer
        created_at:
          type: string
          format: date-time
        promoter:
          $ref: '#/components/schemas/Promoter'
        campaign:
          $ref: '#/components/schemas/Campaign'
        state:
          type: string
          enum:
          - pending
          - accepted
          - rejected
          - blocked
          - inactive
        stats:
          type: object
          properties:
            clicks_count:
              type: integer
            referrals_count:
              type: integer
            sales_count:
              type: integer
            customers_count:
              type: integer
            revenue_amount:
              type: number
        coupon:
          type: string
        display_coupon:
          type: string
        ref_token:
          type: string
        ref_link:
          type: string
        is_customized:
          type: boolean
        direct_url:
          type: string
        referral_rewards_customized:
          type: boolean
        promoter_rewards_customized:
          type: boolean
        rewards_for_promoters:
          type: array
          items:
            $ref: '#/components/schemas/Reward'
        rewards_for_referrals:
          type: array
          items:
            $ref: '#/components/schemas/Reward'
        promo_codes:
          type: array
          items:
            type: string
    Promoter:
      type: object
      properties:
        id:
          type: integer
        email:
          type: string
        name:
          type: string
    Campaign:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        color:
          type: string
    RewardConfig:
      type: object
      required:
      - apply_on
      - product_ids
      - reward_id
      properties:
        apply_on:
          type: string
          enum:
          - monthly
          - yearly
          - one_time
          - all
          - specific
        product_ids:
          type: array
          items:
            type: integer
        reward_id:
          type: integer
    Reward:
      type: object
      properties:
        apply_on:
          type: string
        product_ids:
          type: array
          items:
            type: integer
        reward_id:
          type: integer
        reward:
          type: object
          properties:
            name:
              type: string
            promoter_reward_type:
              type: string
            hide_reward:
              type: boolean
            tier_level:
              type: integer
            coupon:
              type: string
        products:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
    ReferralLink:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        url:
          type: string
        is_default:
          type: boolean
        source:
          type: string
          enum:
          - campaign
          - promoter
        sub_id:
          type: string
        campaign:
          $ref: '#/components/schemas/Campaign'
    ChartData:
      type: object
      properties:
        period_from:
          type: string
          format: date
        period_to:
          type: string
          format: date
        selection:
          type: string
          enum:
          - revenue
          - clicks
          - referrals
          - customers
          - cancellations
        selection_items:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                format: date
              value:
                type: number
        group_by:
          type: string
    PromoterChartData:
      type: object
      properties:
        period_from:
          type: string
          format: date
          description: Start date of the chart data period
        period_to:
          type: string
          format: date
          description: End date of the chart data period
        selection:
          type: string
          description: Type of data being displayed
          enum:
          - revenue
          - clicks
          - referrals
          - customers
          - cancellations
        selection_items:
          type: array
          description: Data points for the chart
          items:
            type: array
            description: A date-value pair
            items:
              oneOf:
              - type: string
                description: Date label for the data point (format depends on group_by)
              - type: number
                description: Value for the data point
            minItems: 2
            maxItems: 2
        group_by:
          type: string
          description: Time unit used for grouping the data
          enum:
          - day
          - week
          - month
          - year
    PromoterProfile:
      type: object
      properties:
        id:
          type: integer
          description: ID of the profile
        first_name:
          type: string
          description: First name of the promoter
        last_name:
          type: string
          description: Last name of the promoter
        website:
          type: string
          nullable: true
          description: Website of the promoter
        company_name:
          type: string
          nullable: true
          description: Company name of the promoter
        company_number:
          type: string
          nullable: true
          description: Company registration number
        phone_number:
          type: string
          nullable: true
          description: Phone number of the promoter
        vat_id:
          type: string
          nullable: true
          description: VAT ID of the promoter
        country:
          type: string
          nullable: true
          description: Country in 2 characters format
          example: US
        address:
          type: string
          nullable: true
          description: Address of the promoter
        avatar:
          type: string
          description: URL to the promoter's avatar image
        w8_form_url:
          type: string
          nullable: true
          description: URL to the promoter's W8 form if available
        w9_form_url:
          type: string
          nullable: true
          description: URL to the promoter's W9 form if available
        description:
          type: string
          nullable: true
          description: Description of the promoter
        invoice_details_validation_errors:
          type: object
          nullable: true
          description: Validation errors for invoice details
        should_validate_invoice_details:
          type: boolean
          description: Should validate invoice details
        instagram_url:
          type: string
          nullable: true
          description: Promoter's Instagram URL
        youtube_url:
          type: string
          nullable: true
          description: Promoter's YouTube URL
        linkedin_url:
          type: string
          nullable: true
          description: Promoter's LinkedIn URL
        facebook_url:
          type: string
          nullable: true
          description: Promoter's Facebook URL
        twitter_url:
          type: string
          nullable: true
          description: Promoter's Twitter URL
        twitch_url:
          type: string
          nullable: true
          description: Promoter's Twitch URL
        tiktok_url:
          type: string
          nullable: true
          description: Promoter's TikTok URL
    PromoterCreate:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          format: email
          description: Email address of the promoter
        cust_id:
          type: string
          nullable: true
          description: Cust ID of the promoter
        profile:
          $ref: '#/components/schemas/PromoterProfile'
        initial_campaign_id:
          type: integer
          description: The ID of the campaign promoter will be added first
        drip_emails:
          type: boolean
          description: Send a welcome email to the promoter
    PromoterUpdate:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Email address of the promoter
        find_by:
          type: string
          enum:
          - email
          - cust_id
          - auth_token
          - ref_token
          - promo_code
          description: "Find by attribute. Required when you want to find the promoter\
            \ using another parameter like the email, cust_id, auth_token, ref_token,\
            \ or promo_code instead of an ID. \n \n  Your request should follow the\
            \ format `https://api.firstpromoter.com/api/v2/company/promoters/{email,\
            \ cust_id, auth_token, ref_token, or promo_code}`"
        cust_id:
          type: string
          nullable: true
          description: Cust ID of the promoter
        custom_fields:
          type: array
          description: "Custom fields must be a Hash with the keys being the ones\
            \ from the company custom fields and values must be String or Array of\
            \ Strings. These are based on the custom fields that you set in your Settings\
            \ > Affiliate portal > Custom fields.\n \n **Note**: Each item will have\
            \ to be set as `custom_fields[my_custom_field_key]: my_custom_field_value`"
        profile:
          $ref: '#/components/schemas/PromoterProfile'
        profile[_destroy_w8form]:
          type: boolean
          description: Destroy W8 form
        profile[_destroy_w9form]:
          type: boolean
          description: Destroy W9 form
    PromoterFilters:
      type: object
      properties:
        revenue_amount:
          type: object
          description: Revenue amount filter
          properties:
            from:
              type: integer
              minimum: 0
              description: Minimum revenue amount
            to:
              type: integer
              description: Maximum revenue amount
        customers_count:
          type: object
          description: Customers count filter
          properties:
            from:
              type: integer
              minimum: 0
              description: Minimum customers count
            to:
              type: integer
              description: Maximum customers count
        referrals_count:
          type: object
          description: Referrals count filter
          properties:
            from:
              type: integer
              minimum: 0
              description: Minimum referrals count
            to:
              type: integer
              description: Maximum referrals count
        clicks_count:
          type: object
          description: Clicks count filter
          properties:
            from:
              type: integer
              minimum: 0
              description: Minimum clicks count
            to:
              type: integer
              description: Maximum clicks count
        joined_at:
          type: object
          description: Joined at filter
          properties:
            from:
              type: string
              description: Minimum joined at date, ISO date format (YYYY-MM-DD HH:MM:SS)
              format: date
            to:
              type: string
              description: Maximum joined at date, ISO date format (YYYY-MM-DD HH:MM:SS)
              format: date
        last_login_at:
          type: object
          description: Last login at filter
          properties:
            from:
              type: string
              format: date
              description: Minimum last login at date, ISO date format (YYYY-MM-DD
                HH:MM:SS)
            to:
              type: string
              format: date
              description: Maximum last login at date, ISO date format (YYYY-MM-DD
                HH:MM:SS)
        campaign_id:
          oneOf:
          - type: integer
            description: Campaign id
          - type: array
            description: Array of campaign ids
            items:
              type: integer
        state:
          type: string
          enum:
          - pending
          - accepted
          - rejected
          - blocked
          - inactive
          - not_set
          description: Promoter state filter
        has_wform:
          type: string
          enum:
          - 'yes'
          - 'no'
          description: Has wform filter
        parent_promoter_id:
          type: integer
          description: Parent promoter id
        archived:
          type: string
          enum:
          - 'true'
          - 'false'
          - '`true`'
          - '`false`'
          - '`yes`'
          - '`no`'
          description: Archived filter
        subscribed_to_email:
          type: string
          enum:
          - 'true'
          - 'false'
          - '`true`'
          - '`false`'
          - '`yes`'
          - '`no`'
          description: Subscribed to email filter
        custom_field1:
          $ref: '#/components/schemas/CustomFieldFilter'
        custom_field2:
          $ref: '#/components/schemas/CustomFieldFilter'
        fraud_suspicions:
          type: array
          items:
            type: string
            enum:
            - same_ip_suspicion
            - same_promoter_email
            - ad_source
            - no_suspicion
            description: Suspicion type filter
        inactivity:
          type: object
          description: Filter promoters by inactivity — promoters who have not performed
            the specified metric within the given number of days
          properties:
            metric:
              type: string
              enum:
              - referral
              - customer
              - click
              - sale
              description: The activity metric to measure inactivity against
            days:
              type: integer
              minimum: 1
              description: Number of days of inactivity
        invoice_details_status:
          type: string
          enum:
          - approved
          - pending
          - rejected
          - not_submitted
          description: Filter promoters by their invoice details status
    CustomFieldFilter:
      type: object
      required:
      - key
      - operator
      - value
      properties:
        key:
          type: string
          description: The key custom_field key
        operator:
          type: string
          enum:
          - exact
          - partial
          description: The custom field operator
        value:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
          description: The value of the custom field. Must be String or Array of strings
    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 result of the referral
        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
        custom_status:
          type: object
          nullable: true
          description: Custom referral status assigned to this referral, if any
          properties:
            id:
              type: integer
            name:
              type: string
            color:
              type: string
              nullable: true
    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
    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
            - cookie
            - manual_admin
            - manual_affiliate
        fraud_check:
          type: array
          items:
            type: string
            enum:
            - no_suspicion
            - same_ip_suspicion
            - same_promoter_email
            - ad_source
        plan_id:
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
    URLsResponse:
      type: array
      items:
        type: object
        properties:
          url:
            type: string
          id:
            type: string
          data:
            type: object
            properties:
              clicks_count:
                type: integer
              revenue_amount:
                type: number
              promoter_earnings_amount:
                type: number
              referrals_count:
                type: integer
              customers_count:
                type: integer
              sales_count:
                type: integer
              refunds_count:
                type: integer
              cancelled_customers_count:
                type: integer
              referrals_to_customers_cr:
                type: number
              clicks_to_customers_cr:
                type: number
              clicks_to_referrals_cr:
                type: number
    Lead:
      type: object
      properties:
        id:
          type: integer
          example: 20738339
        state:
          type: string
          example: cancelled
        email:
          type: string
          example: hello@testmintli.com
        uid:
          type: string
          nullable: true
          example: null
        customer_since:
          type: string
          format: date-time
          example: '2024-09-11T14:22:12.160Z'
        cancelled_at:
          type: string
          format: date-time
          example: '2024-09-11T15:07:46.174Z'
        plan_name:
          type: string
          nullable: true
          example: null
        suspicion:
          type: string
          example: no_suspicion
        username:
          type: string
          nullable: true
          example: null
        website:
          type: string
          nullable: true
          example: null
        created_at:
          type: string
          format: date-time
          example: '2024-09-09T16:22:44.168Z'
        split_promotion_id:
          type: string
          nullable: true
          example: null
        custom_fields:
          type: string
          nullable: true
          example: null
        split_percentage_value:
          type: string
          nullable: true
          example: null
        visitor_sub_id:
          type: string
          nullable: true
          example: null
    WebhookSubscription:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the subscription.
        url:
          type: string
          format: uri
          description: The endpoint URL that receives webhook payloads.
        description:
          type: string
          nullable: true
          description: Optional human-readable label for this subscription.
        event_types:
          type: array
          items:
            type: string
          description: Event type strings this subscription is listening to.
          example:
          - referral.created
          - commission.created
        campaign_ids:
          type: array
          items:
            type: integer
          description: Campaign IDs that trigger this subscription. `[1]` means all
            campaigns.
          example:
          - 1
        active:
          type: boolean
          description: Whether delivery is enabled. Set to `false` to pause without
            deleting.
        timeout:
          type: integer
          description: 'Request timeout in seconds. Must be between 1 and 120. Default:
            30.'
          minimum: 1
          maximum: 120
        max_retries:
          type: integer
          description: 'Number of times a failed delivery is automatically retried.
            Must be between 0 and 10. Default: 3.'
          minimum: 0
          maximum: 10
        headers:
          type: object
          description: Custom HTTP headers sent with every delivery request.
          additionalProperties:
            type: string
          example:
            Authorization: Bearer my-token
        basic_auth_user:
          type: string
          nullable: true
          description: HTTP Basic Auth username sent with every delivery. `null` if
            not configured.
        basic_auth_enabled:
          type: boolean
          description: '`true` when both a Basic Auth username and password are set
            on this subscription.'
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the subscription was created.
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last update.
    WebhookSubscriptionInput:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: The HTTPS URL that will receive webhook payloads. Required
            when creating.
        event_types:
          type: array
          items:
            type: string
          description: One or more event type strings to subscribe to. Required when
            creating. Use the `event_types` endpoint to list all supported values.
          example:
          - referral.created
          - commission.created
        active:
          type: boolean
          description: Enable or pause delivery. Defaults to `true`.
        timeout:
          type: integer
          description: Request timeout in seconds. Must be 1–120. Defaults to 30.
          minimum: 1
          maximum: 120
        max_retries:
          type: integer
          description: Automatic retry count for failed deliveries. Must be 0–10.
            Defaults to 3.
          minimum: 0
          maximum: 10
        description:
          type: string
          description: Optional human-readable label.
        campaign_ids:
          type: array
          items:
            type: integer
          description: Restrict this subscription to events from specific campaigns.
            Pass `[1]` (the default) to receive events from all campaigns.
          example:
          - 1
        headers:
          type: object
          description: Custom HTTP headers to include in every delivery request.
          additionalProperties:
            type: string
          example:
            Authorization: Bearer my-token
        basic_auth_user:
          type: string
          description: HTTP Basic Auth username. Must be set together with `basic_auth_password`.
        basic_auth_password:
          type: string
          description: HTTP Basic Auth password. Write-only — never returned in responses.
            Encrypted at rest.
    WebhookDelivery:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the delivery record.
        event_id:
          type: string
          description: Unique ID of the source event that triggered this delivery.
        event_type:
          type: string
          description: Event type string (e.g. `referral.created`).
        action:
          type: string
          description: The CRUD action that triggered the event (e.g. `created`, `updated`,
            `deleted`).
        entity_type:
          type: string
          description: The type of entity that changed (e.g. `Referral`, `Commission`).
        entity_id:
          type: integer
          nullable: true
          description: The ID of the entity that changed.
        status:
          type: string
          enum:
          - pending
          - delivered
          - retrying
          - failed
          description: Current delivery status. `pending` — queued for delivery. `delivered`
            — endpoint responded with 2xx. `retrying` — delivery failed, waiting for
            next retry attempt. `failed` — all retry attempts exhausted.
        attempts:
          type: integer
          description: Number of delivery attempts made so far.
        last_error:
          type: string
          nullable: true
          description: Error message from the most recent failed attempt (timeout,
            connection error, non-2xx response). `null` on successful delivery.
        response_code:
          type: integer
          nullable: true
          description: HTTP status code returned by your endpoint on the last attempt.
        response_body:
          type: string
          nullable: true
          description: Response body returned by your endpoint on the last attempt
            (truncated if large).
        object_changes:
          type: object
          nullable: true
          description: For `updated` events — a map of changed fields to `[old_value,
            new_value]` pairs.
          example:
            state:
            - lead
            - customer
        payload:
          type: object
          description: The exact JSON payload that was (or will be) sent to your endpoint.
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when this delivery record was created.
        delivered_at:
          type: string
          format: date-time
          nullable: true
          description: ISO 8601 timestamp of when the delivery was acknowledged by
            your endpoint. `null` if not yet delivered.
  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
tags: []