Skip to main content
POST
/
promoters
Create promoter
curl --request POST \
  --url https://api.firstpromoter.com/api/v2/company/promoters \
  --header 'Account-ID: <account-id>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "jsmith@example.com",
  "cust_id": "<string>",
  "profile": {
    "id": 123,
    "first_name": "<string>",
    "last_name": "<string>",
    "website": "<string>",
    "company_name": "<string>",
    "company_number": "<string>",
    "phone_number": "<string>",
    "vat_id": "<string>",
    "country": "US",
    "address": "<string>",
    "avatar": "<string>",
    "w8_form_url": "<string>",
    "w9_form_url": "<string>",
    "description": "<string>",
    "invoice_details_validation_errors": {},
    "should_validate_invoice_details": true,
    "instagram_url": "<string>",
    "youtube_url": "<string>",
    "linkedin_url": "<string>",
    "facebook_url": "<string>",
    "twitter_url": "<string>",
    "twitch_url": "<string>",
    "tiktok_url": "<string>"
  },
  "initial_campaign_id": 123,
  "drip_emails": true
}
'
{
  "id": 123,
  "email": "<string>",
  "name": "<string>",
  "cust_id": "<string>",
  "note": "<string>",
  "stats": {
    "clicks_count": 123,
    "referrals_count": 123,
    "sales_count": 123,
    "customers_count": 123,
    "revenue_amount": 123,
    "active_customers_count": 123
  },
  "is_customized": true,
  "fraud_suspicions": [
    "<string>"
  ],
  "is_confirmed": true,
  "invoice_details_status": "pending",
  "profile": {
    "id": 123,
    "first_name": "<string>",
    "last_name": "<string>",
    "website": "<string>",
    "company_name": "<string>",
    "company_number": "<string>",
    "phone_number": "<string>",
    "vat_id": "<string>",
    "country": "US",
    "address": "<string>",
    "avatar": "<string>",
    "w8_form_url": "<string>",
    "w9_form_url": "<string>",
    "description": "<string>",
    "invoice_details_validation_errors": {},
    "should_validate_invoice_details": true,
    "instagram_url": "<string>",
    "youtube_url": "<string>",
    "linkedin_url": "<string>",
    "facebook_url": "<string>",
    "twitter_url": "<string>",
    "twitch_url": "<string>",
    "tiktok_url": "<string>"
  },
  "joined_at": "2023-11-07T05:31:56Z",
  "last_login_at": "2023-11-07T05:31:56Z",
  "archived_at": "2023-11-07T05:31:56Z",
  "custom_fields": {},
  "password_setup_url": "<string>",
  "first_event_at": "2023-11-07T05:31:56Z",
  "promoter_campaigns": [
    {
      "id": 123,
      "campaign_id": 123,
      "promoter_id": 123,
      "state": "pending",
      "created_at": "2023-11-07T05:31:56Z",
      "campaign": {
        "id": 123,
        "name": "<string>",
        "color": "<string>"
      },
      "coupon": "<string>",
      "ref_token": "<string>",
      "ref_link": "<string>"
    }
  ],
  "balances": {
    "cash": 123,
    "credits": 123,
    "points": 123,
    "free_months": 123,
    "discount": 123
  },
  "track_ad_traffic": true,
  "auth_provider": "<string>",
  "selected_payout_method": {
    "id": 123,
    "method": "<string>",
    "date_added": "2023-11-07T05:31:56Z",
    "is_disabled": true
  },
  "parent_promoter": {
    "id": 123,
    "email": "<string>",
    "name": "<string>"
  }
}

Authorizations

​
Authorization
string
header
required

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

Headers

​
Account-ID
string
required

Account id. You can find your Account ID on Your FirstPromoter Dashboard. Navigate to Settings → Integrations

Body

application/json
​
email
string<email>
required

Email address of the promoter

​
cust_id
string | null

Cust ID of the promoter

​
profile
object
​
initial_campaign_id
integer

The ID of the campaign promoter will be added first

​
drip_emails
boolean

Send a welcome email to the promoter

Response

Promoter created successfully

​
id
integer

Id of the promoter

​
email
string

Email address of the promoter

​
name
string

Full name of the promoter

​
cust_id
string | null

Cust ID of the promoter

​
note
string | null

Optional note about the promoter

​
stats
object

Performance statistics for the promoter

​
is_customized
boolean

Whether the promoter has customized settings

​
fraud_suspicions
string[]

List of potential fraud flags

​
is_confirmed
boolean

Whether the promoter has confirmed their account

​
invoice_details_status
enum<string>

Status of the promoter's invoice details

Available options:
pending,
approved,
denied
​
profile
object
​
joined_at
string<date-time>

Date and time when the promoter joined.

​
last_login_at
string<date-time> | null

Date and time of the promoter's last login.

​
archived_at
string<date-time> | null

Date and time when the promoter was archived, if applicable.

​
custom_fields
object

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
string | null

URL for the promoter to set up their password

​
first_event_at
string<date-time>

Date and time of the promoter's first activity.

​
promoter_campaigns
object[]

List of campaigns associated with the promoter

​
balances
object

Earnings balance breakdown for the promoter

​
track_ad_traffic
boolean | null

Whether ad traffic tracking is enabled for this promoter. Null means the campaign default is used.

​
auth_provider
string | null

OAuth provider used to authenticate (e.g. google). Null if using email/password.

​
selected_payout_method
object

The promoter's currently selected payout method. Omitted when the exclude_payout_method=true query parameter is set.

​
parent_promoter
object

The parent promoter (for sub-affiliate relationships). Only included when the include_parent_promoter=true query parameter is set.