FirstPromoter Admin API

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
      ta

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