> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firstpromoter.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get available promoters
> With this endpoint you can list all promoters.
**HTTP Request**
`GET https://api.firstpromoter.com/api/v2/company/promoters`
## OpenAPI
````yaml openapi-v2-promoters get /promoters
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:
tags:
- Promoters
summary: Get available promoters
description: |-
With this endpoint you can list all promoters.
**HTTP Request**
`GET https://api.firstpromoter.com/api/v2/company/promoters`
operationId: getPromoters
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
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:
PromoterFilters:
type: object
properties:
revenue_amount:
type: object
description: Revenue amount filter
properties:
from:
type: integer
minimum: 0
description: Minimum revenue amount
to:
type: integer
description: Maximum revenue amount
customers_count:
type: object
description: Customers count filter
properties:
from:
type: integer
minimum: 0
description: Minimum customers count
to:
type: integer
description: Maximum customers count
referrals_count:
type: object
description: Referrals count filter
properties:
from:
type: integer
minimum: 0
description: Minimum referrals count
to:
type: integer
description: Maximum referrals count
clicks_count:
type: object
description: Clicks count filter
properties:
from:
type: integer
minimum: 0
description: Minimum clicks count
to:
type: integer
description: Maximum clicks count
joined_at:
type: object
description: Joined at filter
properties:
from:
type: string
description: Minimum joined at date, ISO date format (YYYY-MM-DD HH:MM:SS)
format: date
to:
type: string
description: Maximum joined at date, ISO date format (YYYY-MM-DD HH:MM:SS)
format: date
last_login_at:
type: object
description: Last login at filter
properties:
from:
type: string
format: date
description: >-
Minimum last login at date, ISO date format (YYYY-MM-DD
HH:MM:SS)
to:
type: string
format: date
description: >-
Maximum last login at date, ISO date format (YYYY-MM-DD
HH:MM:SS)
campaign_id:
oneOf:
- type: integer
description: Campaign id
- type: array
description: Array of campaign ids
items:
type: integer
state:
type: string
enum:
- pending
- accepted
- rejected
- blocked
- inactive
- not_set
description: Promoter state filter
has_wform:
type: string
enum:
- 'yes'
- 'no'
description: Has wform filter
parent_promoter_id:
type: integer
description: Parent promoter id
archived:
type: string
enum:
- 'true'
- 'false'
- '`true`'
- '`false`'
- '`yes`'
- '`no`'
description: Archived filter
subscribed_to_email:
type: string
enum:
- 'true'
- 'false'
- '`true`'
- '`false`'
- '`yes`'
- '`no`'
description: Subscribed to email filter
custom_field1:
$ref: '#/components/schemas/CustomFieldFilter'
custom_field2:
$ref: '#/components/schemas/CustomFieldFilter'
fraud_suspicions:
type: array
items:
type: string
enum:
- same_ip_suspicion
- same_promoter_email
- ad_source
- no_suspicion
description: Suspicion type filter
inactivity:
type: object
description: >-
Filter promoters by inactivity — promoters who have not performed
the specified metric within the given number of days
properties:
metric:
type: string
enum:
- referral
- customer
- click
- sale
description: The activity metric to measure inactivity against
days:
type: integer
minimum: 1
description: Number of days of inactivity
invoice_details_status:
type: string
enum:
- approved
- pending
- rejected
- not_submitted
description: Filter promoters by their invoice details status
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:
- pending
- approved
- denied
profile:
$ref: '#/components/schemas/PromoterProfile'
joined_at:
type: string
format: date-time
description: Date and time when the promoter joined.
last_login_at:
type: string
format: date-time
nullable: true
description: Date and time of the promoter's last login.
archived_at:
type: string
format: date-time
nullable: true
description: Date and time when the promoter was archived, if applicable.
custom_fields:
type: object
nullable: true
description: >-
Custom fields for the promoter, based on company settings. This is a
key-value pair object where keys are custom field identifiers and
values are the corresponding data.
password_setup_url:
type: string
nullable: true
description: URL for the promoter to set up their password
first_event_at:
type: string
format: date-time
description: Date and time of the promoter's first activity.
promoter_campaigns:
type: array
description: List of campaigns associated with the promoter
items:
type: object
properties:
id:
type: integer
description: ID of the promoter-campaign association
campaign_id:
type: integer
description: ID of the campaign
promoter_id:
type: integer
description: ID of the promoter
state:
type: string
description: State of the promoter in this campaign
enum:
- pending
- accepted
- rejected
- blocked
- inactive
- not_set
created_at:
type: string
format: date-time
description: When the promoter was added to the campaign
campaign:
type: object
properties:
id:
type: integer
description: ID of the campaign
name:
type: string
description: Name of the campaign
color:
type: string
description: Color code associated with the campaign
coupon:
type: string
description: Coupon code for this campaign
ref_token:
type: string
description: Referral token for this campaign
ref_link:
type: string
description: Referral link for this campaign
balances:
type: object
description: Earnings balance breakdown for the promoter
properties:
cash:
type: number
nullable: true
credits:
type: number
nullable: true
points:
type: number
nullable: true
free_months:
type: number
nullable: true
discount:
type: number
nullable: true
track_ad_traffic:
type: boolean
nullable: true
description: >-
Whether ad traffic tracking is enabled for this promoter. Null means
the campaign default is used.
auth_provider:
type: string
nullable: true
description: >-
OAuth provider used to authenticate (e.g. google). Null if using
email/password.
selected_payout_method:
type: object
nullable: true
description: >-
The promoter's currently selected payout method. Omitted when the
`exclude_payout_method=true` query parameter is set.
properties:
id:
type: integer
method:
type: string
date_added:
type: string
format: date-time
is_disabled:
type: boolean
parent_promoter:
type: object
nullable: true
description: >-
The parent promoter (for sub-affiliate relationships). Only included
when the `include_parent_promoter=true` query parameter is set.
properties:
id:
type: integer
email:
type: string
name:
type: string
nullable: true
CustomFieldFilter:
type: object
required:
- key
- operator
- value
properties:
key:
type: string
description: The key custom_field key
operator:
type: string
enum:
- exact
- partial
description: The custom field operator
value:
oneOf:
- type: string
- type: array
items:
type: string
description: The value of the custom field. Must be String or Array of strings
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
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
API key passed as a Bearer token in the Authorization header. You can
find your API Key on Your FirstPromoter Dashboard. Navigate to Settings
→ Integrations section → Manage API Keys
````