openapi: 3.0.1
info:
title: FirstPromoter Admin Commissions Promoters 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: []
tags:
- name: Promoters
paths:
/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'
components:
schemas:
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
Promoter:
type: object
properties:
id:
type: integer
email:
type: string
name:
type: string
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
Ids:
type: array
items:
type: integer
description: Array of Payout IDs
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 pr
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/firstpromoter/refs/heads/main/openapi/firstpromoter-promoters-api-openapi.yml