FirstPromoter Promoters API

openapi: 3.2.0
info:
  title: Firstpromoter Promoters API
  version: '1.0'
  description: 'Operations tagged Promoters across 2 of this provider''s published API definitions: firstpromoter-v2-affiliate-promoters-openapi.yml, firstpromoter-v2-promoters-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.firstpromoter.com/api/v2/affiliate
- url: https://api.firstpromoter.com/api/v2/company
security:
- BearerAuth: []
tags:
- name: Promoters
paths:
  /promoters/current:
    get:
      summary: Get current promoter
      tags:
      - Promoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Promoter'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: string
    servers:
    - url: https://api.firstpromoter.com/api/v2/affiliate
  /promoters/sub_affiliates:
    get:
      summary: Get current promoter sub affiliates
      tags:
      - Promoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubAffiliate'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    servers:
    - url: https://api.firstpromoter.com/api/v2/affiliate
  /promoters/chart_data:
    get:
      summary: Get chart data
      tags:
      - Promoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: promoter_campaign_id
        in: query
        description: If provided, the given promoter campaign will be used in chart. Otherwise all the current_promoter campaigns will be used.
        schema:
          type: integer
      - name: period_from
        in: query
        schema:
          type: string
          format: date
      - name: period_to
        in: query
        schema:
          type: string
          format: date
      - name: selection
        in: query
        schema:
          type: string
          enum:
          - revenue
          - commissions
          - clicks
          - referrals
          - customers
          - cancellations
      responses:
        '401':
          description: Unauthorized
    servers:
    - url: https://api.firstpromoter.com/api/v2/affiliate
  /promoters/email_from_encrypted_id:
    get:
      summary: Get the promoter email
      tags:
      - Promoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: id
        in: query
        required: true
        description: The encrypted id
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
        '422':
          description: Unprocessable Entity
    servers:
    - url: https://api.firstpromoter.com/api/v2/affiliate
  /promoters/set_password:
    put:
      summary: Set the user password
      tags:
      - Promoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              - user
              properties:
                id:
                  type: string
                  description: The encrypted id
                user:
                  type: object
                  required:
                  - new_password
                  - new_password_confirmation
                  properties:
                    new_password:
                      type: string
                    new_password_confirmation:
                      type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Promoter'
        '422':
          description: Unprocessable Entity
    servers:
    - url: https://api.firstpromoter.com/api/v2/affiliate
  /promoters/archive:
    post:
      summary: Archives current promoter
      tags:
      - Promoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Successful response
        '401':
          description: Unauthorized
        '422':
          description: Unprocessable Entity
    servers:
    - url: https://api.firstpromoter.com/api/v2/affiliate
  /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_2'
      - 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/PromoterListItem'
                    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_2'
      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_2'
        '401':
          description: Unauthorized
    servers:
    - url: https://api.firstpromoter.com/api/v2/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_2'
      - 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_2'
        '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_2'
      - 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_2'
        '401':
          description: Unauthorized
    servers:
    - url: https://api.firstpromoter.com/api/v2/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_2'
      - 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
    servers:
    - url: https://api.firstpromoter.com/api/v2/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_2'
      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'
    servers:
    - url: https://api.firstpromoter.com/api/v2/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_2'
      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'
    servers:
    - url: https://api.firstpromoter.com/api/v2/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_2'
      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'
    servers:
    - url: https://api.firstpromoter.com/api/v2/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_2'
      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'
    servers:
    - url: https://api.firstpromoter.com/api/v2/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_2'
      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'
    servers:
    - url: https://api.firstpromoter.com/api/v2/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_2'
      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'
    servers:
    - url: https://api.firstpromoter.com/api/v2/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_2'
      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'
    servers:
    - url: https://api.firstpromoter.com/api/v2/company
components:
  schemas:
    Promoter:
      type: object
      properties:
        id:
          type: integer
        email:
          type: string
        name:
          type: string
        stats:
          type: object
          properties:
            clicks_count:
              type: integer
            referrals_count:
              type: integer
            sales_count:
              type: integer
            customers_count:
              type: integer
            revenue_amount:
              type: number
            active_customers_count:
              type: integer
        balances:
          type: object
        custom_fields:
          type: object
        first_event_at:
          type: string
          format: date-time
        invoice_details_status:
          type: string
        joined_at:
          type: string
          format: date-time
        selected_payout_method:
          type: string
        pending_contract_documents:
          type: array
          items:
            type: string
        profile:
          $ref: '#/components/schemas/PromoterProfile'
        promoter_campaigns:
          type: array
          items:
            $ref: '#/components/schemas/PromoterCampaign'
        is_confirmed:
          type: boolean
    PromoterProfile:
      type: object
      properties:
        id:
          type: integer
        first_name:
          type: string
        last_name:
          type: string
        website:
          type: string
        company_name:
          type: string
        phone_number:
          type: string
        vat_id:
          type: string
        country:
          type: string
        address:
          type: string
        avatar:
          type: string
        instagram_url:
          type: string
        youtube_url:
          type: string
        linkedin_url:
          type: string
        facebook_url:
      

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