FirstPromoter Promoters API - 13 operation(s) on the admin (api/v2/company) surface, from FirstPromoter's own published OpenAPI definition (3.0.1) indexed in https://docs.firstpromoter.com/llms.txt.
openapi: 3.0.1
info:
title: FirstPromoter API
version: '1.0'
description: API documentation for FirstPromoter promoters management
servers:
- url: https://api.firstpromoter.com/api/v2/company
security:
- BearerAuth: []
paths:
/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/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'
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
/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
/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
/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'
/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'
/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'
/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'
/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'
/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'
/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'
/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:
parameters:
AccountId:
name: Account-ID
in: header
required: true
description: Account id. You can find your Account ID on Your FirstPromoter Dashboard. Navigate to Settings → Integrations
schema:
type: string
schemas:
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 promoters
selected_total:
type: integer
description: Total number of selected promoters
processed_count:
type: integer
description: Number of processed promoters
failed_count:
type: integer
description: Number of failed promoters
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
ErrorResponse:
type: object
properties:
message:
type: string
description: Error message
code:
type: string
description: Error code
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
description: Id of the promoter
email:
type: string
description: Email address of the promoter
name:
type: string
description: Full name of the promoter
cust_id:
type: string
nullable: true
description: Cust ID of the promoter
note:
type: string
nullable: true
description: Optional note about the promoter
stats:
type: object
description: Performance statistics for the promoter
properties:
clicks_count:
type: integer
description: Number of clicks generated
referrals_count:
type: integer
description: Number of referrals generated
sales_count:
type: integer
description: Number of sales generated
customers_count:
type: integer
description: Number of customers referred
revenue_amount:
type: integer
description: Total revenue generated
active_customers_count:
type: integer
description: Number of active customers
is_customized:
type: boolean
description: Whether the promoter has customized settings
fraud_suspicions:
type: array
description: List of potential fraud flags
items:
type: string
is_confirmed:
type: boolean
description: Whether the promoter has confirmed their account
invoice_details_status:
type: string
description: Status of the promoter's invoice details
enum:
- pe
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/firstpromoter/refs/heads/main/openapi/firstpromoter-v2-promoters-openapi.yml