> ## 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.
# List promoters
> Use this endpoint to list your promoters using the API. The response will return the promoters as JSON array. Pagination details are held on response headers. Add `--include` option on `curl` request to see the pagination details format and links to next pages.**HTTP Request**
`GET https://firstpromoter.com/api/v1/promoters/list`
Use this endpoint to list your promoters using the API. The response will return the promoters as JSON array.
Pagination details are held on response headers. Add --include option on curl request to see the pagination details format and links to next pages.
## OpenAPI
````yaml openapi-promoters GET /list
openapi: 3.0.1
info:
title: FirstPromoter Promoters API
description: >-
The Promoters API endpoint allows you to manage your affiliates/promoters
through API calls. The most important use case is to automatically create
promoter accounts for your customers.
license:
name: MIT
version: 1.0.0
servers:
- url: https://firstpromoter.com/api/v1/promoters
security:
- apiKeyAuth: []
paths:
/list:
get:
description: >-
Use this endpoint to list your promoters using the API. The response
will return the promoters as JSON array. Pagination details are
held on response headers. Add `--include` option on `curl` request to
see the pagination details format and links to next
pages.**HTTP Request**
`GET
https://firstpromoter.com/api/v1/promoters/list`
parameters:
- name: campaign_id
in: query
description: List all promoters accepted to a specific campaign.
schema:
type: string
responses:
'200':
description: List Promoters response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Promoter'
example:
- id: 8815216
status: active
cust_id: null
email: mintly@mailinator.com
created_at: '2024-09-11T14:20:50.403Z'
temp_password: 1y-JxB
default_promotion_id: 10116083
pref: y3fvz4o
default_ref_id: heubv
note: null
w8_form_url: null
w9_form_url: null
parent_promoter_id: null
earnings_balance: null
current_balance: null
paid_balance: null
auth_token: X9edc-csF56dt8qB6KwcDyPhVdMUtWXY
profile:
id: 8862106
first_name: null
last_name: null
website: null
company_name: null
phone_number: null
address: null
vat_id: null
country: null
paypal_email: null
avatar_url: null
description: null
social_accounts: {}
promotions:
- id: 10116083
status: offer_running
ref_id: heubv
promo_code: null
customer_promo_code: null
target_reached_at: null
promoter_id: 8815216
campaign_id: 26127
referral_link: https://lastechworld.com?fpr=heubv
current_offer:
id: 140358
name: 1 free subscription months
amount: 1
unit: free_months
default_promo_code: ''
current_referral_reward:
id: 140359
amount: 1
type: per_referral
unit: free_months
name: 1 free subscription months
per_of_sale: 0
default_promo_code: ''
current_promotion_reward: null
current_target_reward: null
campaign_name: Make Campaign
hidden: false
visitors_count: 0
leads_count: 0
customers_count: 0
refunds_count: 0
cancellations_count: 0
sales_count: 0
sales_total: 0
refunds_total: 0
active_customers_count: 0
- id: 8809547
status: active
cust_id: null
email: prince+grace@mailinator.com
created_at: '2024-09-09T22:01:16.909Z'
temp_password: yx4_LJ
default_promotion_id: 10108807
pref: udicfs6
default_ref_id: ljysw
note: null
w8_form_url: null
w9_form_url: null
parent_promoter_id: null
earnings_balance: null
current_balance: null
paid_balance: null
auth_token: kitwmn6ER9RzfZ5Mn9Ksv8PFxnpAzwBT
profile:
id: 8856384
first_name: null
last_name: null
website: null
company_name: null
phone_number: null
address: null
vat_id: null
country: null
paypal_email: null
avatar_url: null
description: null
social_accounts: {}
promotions:
- id: 10108807
status: offer_running
ref_id: ljysw
promo_code: null
customer_promo_code: null
target_reached_at: null
promoter_id: 8809547
campaign_id: 26127
referral_link: https://lastechworld.com?fpr=ljysw
current_offer:
id: 140358
name: 1 free subscription months
amount: 1
unit: free_months
default_promo_code: ''
current_referral_reward:
id: 140359
amount: 1
type: per_referral
unit: free_months
name: 1 free subscription months
per_of_sale: 0
default_promo_code: ''
current_promotion_reward: null
current_target_reward: null
campaign_name: Make Campaign
hidden: false
visitors_count: 0
leads_count: 0
customers_count: 0
refunds_count: 0
cancellations_count: 0
sales_count: 0
sales_total: 0
refunds_total: 0
active_customers_count: 0
'401':
description: Authentication Error
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationError'
example: Bad credentials
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityErrorType1'
example:
error: Campaign not found.
components:
schemas:
Promoter:
type: object
properties:
id:
description: The promoter's ID inside FirstPromoter
type: integer
status:
description: Promoter's status
type: string
enum:
- approved
- pending
- denied
cust_id:
description: >-
Your customer's user ID inside your application/system for the
promoter. This will be included in the webhook event and can be used
to identify the promoter in your system if you subscribe for
FirstPromoter's webhooks.
type: string
email:
description: Promoter's email
type: string
created_at:
description: ISO date string when the promoter signed up
type: string
temp_password:
description: >-
A temporary password the promoter can use to log in to their
dashboard if you don't use authentication tokens(`auth_token`) to
sign promoters in automatically.
type: string
default_promotion_id:
description: Promoter's default promotion id
type: number
example: 128833
pref:
description: Promoter's parent referral id.
type: string
default_ref_id:
description: Promoter's default referral id
type: string
note:
description: A note/description of promoter
type: string
w8_form_url:
description: The w8 form url
type: string
w9_form_url:
description: The w9 form url
type: string
parent_promoter_id:
description: Parent promoter id
type: string
earnings_balance:
description: >-
Promoter's earnings balance. This object can contain `cash`,
`credits`, `discount_per`
type: object
properties:
cash:
description: The cash earnings
type: integer
example: 3000
credits:
description: The earning credits
type: integer
example: 300
discount_per:
description: The earning discount percentage
type: integer
example: 30
current_balance:
description: >-
Promoter's current balance. This object can contain `cash`,
`credits`, `discount_per`
type: object
properties:
cash:
description: The current cash balance
type: integer
example: 1000
credits:
description: The current credits
type: integer
example: 200
discount_per:
description: The current discount percentage
type: integer
example: 15
paid_balance:
description: >-
Promoter's paid balance. This object can contain `cash`, `credits`,
`discount_per`
type: object
properties:
cash:
description: The cash paid
type: integer
example: 2000
credits:
description: The credits given
type: integer
example: 100
discount_per:
description: The discount percentage given
type: integer
example: 15
auth_token:
description: Authentication token generated when the promoter was created
type: string
profile:
$ref: '#/components/schemas/PromoterProfile'
promotions:
type: array
items:
$ref: '#/components/schemas/Promotion'
custom_fields:
type: object
nullable: true
description: Key-value pairs of custom fields configured for this promoter
promo_codes:
type: array
description: Promo codes associated with this promoter
items:
type: object
properties:
id:
type: integer
code:
type: string
reward:
type: object
properties:
id:
type: integer
name:
type: string
AuthenticationError:
type: string
UnprocessableEntityErrorType1:
required:
- error
type: object
properties:
error:
type: string
PromoterProfile:
type: object
properties:
first_name:
description: Promoter's first name
type: string
last_name:
description: Promoter's last name
type: string
website:
description: Promoter's website
type: string
company_name:
description: Promoter's company name
type: string
phone_number:
description: Promoter's phone number
type: string
address:
description: Promoter's address
type: string
vat_id:
description: Promoter's vat id
type: string
country:
description: Promoter's country
type: string
paypal_email:
description: Promoter's Paypal email address
type: string
avatar_url:
description: URL of the profile picture promoters can see on their dashboard
type: string
description:
description: A note/description of promoter
type: string
social_accounts:
$ref: '#/components/schemas/SocialAccounts'
Promotion:
type: object
properties:
id:
description: ID of the promotion.
type: number
status:
description: Current offer status.
type: string
ref_id:
type: string
promo_code:
description: ' Unique promo code from your billing provider to assign to this affiliate for coupon tracking. This is also known as the `Coupon Code` or `Coupon ID`'
type: string
customer_promo_code:
description: >-
Customer promo code from your billing provider assigned to this
affiliate for coupon tracking. This is also known as `discount code`
or `promotion code` or `display code`. This is the code your
customer(s) used on the checkout form/page.
type: string
target_reached_at:
type: object
promoter_id:
description: ID of the promoter/affiliate.
type: number
campaign_id:
description: ID of the campaign where the promotion runs.
type: number
referral_link:
description: Promoter's referral link
type: string
current_offer:
type: object
properties:
id:
description: The reward id
type: number
name:
description: The reward name
type: string
amount:
description: The reward amount
type: number
unit:
description: The reward unit (e.g., 'credits', 'free_months', 'cash').
type: string
default_promo_code:
type: string
current_referral_reward:
type: object
properties:
id:
type: number
amount:
type: number
unit:
type: string
name:
type: string
per_of_sale:
type: number
default_promo_code:
type: string
current_promotion_reward:
type: object
current_target_reward:
type: object
campaign_name:
type: string
hidden:
type: boolean
visitors_count:
type: number
leads_count:
type: number
customers_count:
type: number
refunds_count:
type: number
cancellations_count:
type: number
sales_count:
type: number
sales_total:
type: number
refunds_total:
type: number
active_customers_count:
type: number
SocialAccounts:
type: object
properties:
twitter:
type: object
properties:
url:
description: Promoter's twitter url
type: string
youtube:
type: object
properties:
url:
description: Promoter's youtube url
type: string
facebook:
type: object
properties:
url:
description: Promoter's Facebook url
type: string
linkedin:
type: object
properties:
url:
description: Promoter's linkedin url
type: string
instagram:
type: object
properties:
url:
description: Promoter's instagram url
type: string
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
````