> ## 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.
# Add a promoter to a campaign
> Use this endpoint to add a promoter to another campaign. Your promoter can have multiple campaigns to promote, each with its own referral link and referral ID.
You can identify promoters by `id`, `cust_id`, `auth_token`, `promoter_email` or `ref_id` (referral id). **HTTP Request**
`POST https://firstpromoter.com/api/v1/promoters/add_to_campaign`
Use this endpoint to add a promoter to another campaign. Your promoter will have multiple campaigns to promoter, each campaign with its own promotion, referral link and referral id.
You can identify promoters **by: id, cust\_id, auth\_token, promoter\_email or ref\_id**(referral id).
## OpenAPI
````yaml openapi-promoters POST /add_to_campaign
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:
/add_to_campaign:
post:
description: >-
Use this endpoint to add a promoter to another campaign. Your promoter
can have multiple campaigns to promote, each with its own referral link
and referral ID.
You can identify promoters by `id`, `cust_id`,
`auth_token`, `promoter_email` or `ref_id` (referral id). **HTTP
Request**
`POST
https://firstpromoter.com/api/v1/promoters/add_to_campaign`
parameters:
- name: id
in: query
description: Promoter's ID inside FirstPromoter
schema:
type: string
- name: promoter_email
in: query
description: Email of the promoter
schema:
type: string
- name: cust_id
in: query
description: Assigned customer/user ID
schema:
type: string
- name: ref_id
in: query
description: Referral ID
schema:
type: string
- name: auth_token
in: query
description: Authentication token generated when the promoter was created
schema:
type: string
- name: campaign_id
in: query
required: true
description: >-
ID of the campaign to add the promoter to. It can be found on the
url bar when editing the campaign
schema:
type: string
responses:
'200':
description: Add to campaign response
content:
application/json:
schema:
$ref: '#/components/schemas/Promoter'
example:
id: 5594994
status: active
cust_id: null
email: wopomipu@mailinator.com
created_at: '2023-04-04T12:30:23.250Z'
temp_password: Pa$$w0rd!
default_promotion_id: 6041923
pref: jme34om
default_ref_id: cd5de
note: null
w8_form_url: null
w9_form_url: null
parent_promoter_id: null
earnings_balance:
cash: 30000
current_balance:
credits: -150
paid_balance:
cash: 30000
credits: 150
auth_token: cxXz22oP5xNG2bFcXzo13N8HQ91RYed2
profile:
id: 5629748
first_name: Raven
last_name: Moore
website: null
company_name: null
phone_number: null
address: null
vat_id: null
country: null
paypal_email: nyhuxigyn@mailinator.com
avatar_url: null
description: null
social_accounts: {}
promotions:
- id: 10122408
status: offer_inactive
ref_id: s7rxl
promo_code: null
customer_promo_code: null
target_reached_at: null
promoter_id: 5594994
campaign_id: 18747
referral_link: https://lastechworld.com?fpr=s7rxl
current_offer: null
current_referral_reward:
id: 94230
amount: 0
type: per_referral
unit: cash
name: 20% recurring commission
per_of_sale: 20
default_promo_code: ''
current_promotion_reward: null
current_target_reward: null
campaign_name: Publishers & marketing Partners
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: 10122364
status: offer_running
ref_id: 4us60
promo_code: null
customer_promo_code: null
target_reached_at: null
promoter_id: 5594994
campaign_id: 26127
referral_link: https://lastechworld.com?fpr=4us60
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: 6041923
status: offer_running
ref_id: cd5de
promo_code: ''
customer_promo_code: ''
target_reached_at: null
promoter_id: 5594994
campaign_id: 18519
referral_link: https://partner.lastechworld.com?fpr=cd5de
current_offer:
id: 96412
name: 75 credits
amount: 75
unit: credits
default_promo_code: ''
current_referral_reward:
id: 93868
amount: null
type: per_referral
unit: cash
name: 15% recurring commission
per_of_sale: 15
default_promo_code: null
current_promotion_reward: null
current_target_reward: null
campaign_name: TechScenario12Campaign-1
hidden: false
visitors_count: 1
leads_count: 1
customers_count: 1
refunds_count: 0
cancellations_count: 0
sales_count: 2
sales_total: 250000
refunds_total: 0
active_customers_count: 1
'401':
description: Authentication Error
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationError'
example: Bad credentials
'404':
description: Not Found Error
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityErrorType1'
example:
error: Promoter not found.
'422':
description: Unprocessable Entity Error
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityErrorType1'
example:
error: >-
You need to find the promoter either by id, cust_id,
auth_token, ref_id or promoter_email
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
````