Get available promoters

curl --request GET \
  --url https://api.firstpromoter.com/api/v2/company/promoters \
  --header 'Account-ID: <account-id>' \
  --header 'Authorization: Bearer <token>'

{
  "data": [
    {
      "id": 123,
      "email": "<string>",
      "name": "<string>",
      "cust_id": "<string>",
      "note": "<string>",
      "state": "pending",
      "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",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_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>"
        }
      ]
    }
  ],
  "meta": {
    "pending_count": 123
  }
}

GET

promoters

Get available promoters

curl --request GET \
  --url https://api.firstpromoter.com/api/v2/company/promoters \
  --header 'Account-ID: <account-id>' \
  --header 'Authorization: Bearer <token>'

{
  "data": [
    {
      "id": 123,
      "email": "<string>",
      "name": "<string>",
      "cust_id": "<string>",
      "note": "<string>",
      "state": "pending",
      "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",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_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>"
        }
      ]
    }
  ],
  "meta": {
    "pending_count": 123
  }
}

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

Query Parameters

string

Search params for promoters, search using, email, name or ref_id

ids[]

integer[]

Array of promoter ids to get

filters

object

Filter params

Show child attributes

filters.revenue_amount

object

Revenue amount filter

Show child attributes

filters.revenue_amount.from

integer

Minimum revenue amount

Required range: x >= 0

filters.revenue_amount.to

integer

Maximum revenue amount

filters.customers_count

object

Customers count filter

Show child attributes

filters.customers_count.from

integer

Minimum customers count

Required range: x >= 0

filters.customers_count.to

integer

Maximum customers count

filters.referrals_count

object

Referrals count filter

Show child attributes

filters.referrals_count.from

integer

Minimum referrals count

Required range: x >= 0

filters.referrals_count.to

integer

Maximum referrals count

filters.clicks_count

object

Clicks count filter

Show child attributes

filters.clicks_count.from

integer

Minimum clicks count

Required range: x >= 0

filters.clicks_count.to

integer

Maximum clicks count

filters.joined_at

object

Joined at filter

Show child attributes

filters.joined_at.from

string<date>

Minimum joined at date, ISO date format (YYYY-MM-DD HH:MM:SS)

filters.joined_at.to

string<date>

Maximum joined at date, ISO date format (YYYY-MM-DD HH:MM:SS)

Last login at filter

Show child attributes

Minimum last login at date, ISO date format (YYYY-MM-DD HH:MM:SS)

Maximum last login at date, ISO date format (YYYY-MM-DD HH:MM:SS)

filters.campaign_id

Campaign id

filters.state

enum<string>

Promoter state filter

Available options:

pending,

accepted,

rejected,

blocked,

inactive,

not_set

filters.has_wform

enum<string>

Has wform filter

Available options:

yes,

no

filters.parent_promoter_id

integer

Parent promoter id

filters.archived

enum<string>

Archived filter

Available options:

true,

false,

`true`,

`false`,

`yes`,

`no`

filters.subscribed_to_email

enum<string>

Subscribed to email filter

Available options:

true,

false,

`true`,

`false`,

`yes`,

`no`

filters.custom_field1

object

Show child attributes

filters.custom_field1.key

string

required

The key custom_field key

filters.custom_field1.operator

enum<string>

required

The custom field operator

Available options:

exact,

partial

filters.custom_field1.value

required

The value of the custom field. Must be String or Array of strings

filters.custom_field2

object

Show child attributes

filters.custom_field2.key

string

required

The key custom_field key

filters.custom_field2.operator

enum<string>

required

The custom field operator

Available options:

exact,

partial

filters.custom_field2.value

required

The value of the custom field. Must be String or Array of strings

filters.fraud_suspicions

enum<string>[]

Suspicion type filter

Available options:

same_ip_suspicion,

same_promoter_email,

ad_source,

no_suspicion

sorting

object

Sorting params

Show child attributes

sorting.clicks_count

enum<string>

Available options:

asc,

desc

sorting.referrals_count

enum<string>

Available options:

asc,

desc

sorting.customers_count

enum<string>

Available options:

asc,

desc

sorting.revenue_amount

enum<string>

Available options:

asc,

desc

sorting.joined_at

enum<string>

Available options:

asc,

desc

Response

Successful response

data

object[]

List of Promoters

Show child attributes

data.id

integer

Id of the promoter

data.email

string

Email address of the promoter

data.name

string

Full name of the promoter

data.cust_id

string | null

Cust ID of the promoter

data.note

string | null

Optional note about the promoter

data.state

enum<string>

State of the promoter.

Available options:

pending,

accepted,

rejected,

blocked,

inactive,

not_set

data.stats

object

Performance statistics for the promoter

Show child attributes

data.stats.clicks_count

integer

Number of clicks generated

data.stats.referrals_count

integer

Number of referrals generated

data.stats.sales_count

integer

Number of sales generated

data.stats.customers_count

integer

Number of customers referred

data.stats.revenue_amount

integer

Total revenue generated

data.stats.active_customers_count

integer

Number of active customers

data.is_customized

boolean

Whether the promoter has customized settings

data.fraud_suspicions

string[]

List of potential fraud flags

data.is_confirmed

boolean

Whether the promoter has confirmed their account

data.invoice_details_status

enum<string>

Status of the promoter's invoice details

Available options:

pending,

approved,

denied

data.profile

object

Show child attributes

data.profile.id

integer

ID of the profile

data.profile.first_name

string

First name of the promoter

data.profile.last_name

string

Last name of the promoter

data.profile.website

string | null

Website of the promoter

data.profile.company_name

string | null

Company name of the promoter

data.profile.company_number

string | null

Company registration number

data.profile.phone_number

string | null

Phone number of the promoter

data.profile.vat_id

string | null

VAT ID of the promoter

data.profile.country

string | null

Country in 2 characters format

Example:

"US"

data.profile.address

string | null

Address of the promoter

data.profile.avatar

string

URL to the promoter's avatar image

data.profile.w8_form_url

string | null

URL to the promoter's W8 form if available

data.profile.w9_form_url

string | null

URL to the promoter's W9 form if available

data.profile.description

string | null

Description of the promoter

data.profile.invoice_details_validation_errors

object

Validation errors for invoice details

data.profile.should_validate_invoice_details

boolean

Should validate invoice details

data.profile.instagram_url

string | null

Promoter's Instagram URL

data.profile.youtube_url

string | null

Promoter's YouTube URL

data.profile.linkedin_url

string | null

Promoter's LinkedIn URL

data.profile.facebook_url

string | null

Promoter's Facebook URL

data.profile.twitter_url

string | null

Promoter's Twitter URL

data.profile.twitch_url

string | null

Promoter's Twitch URL

data.profile.tiktok_url

string | null

Promoter's TikTok URL

data.joined_at

string<date-time>

Date and time when the promoter joined.

Date and time of the promoter's last login.

data.archived_at

string<date-time> | null

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

data.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.

data.password_setup_url

string | null

URL for the promoter to set up their password

data.first_event_at

string<date-time>

Date and time of the promoter's first activity.

data.created_at

string<date-time>

Date and time when the promoter was created. ISO date format (YYYY-MM-DD HH:MM:SS)

data.updated_at

string<date-time>

Date and time when the promoter was last updated. ISO date format (YYYY-MM-DD HH:MM:SS)

data.promoter_campaigns

object[]

List of campaigns associated with the promoter

Show child attributes

data.promoter_campaigns.id

integer

ID of the promoter-campaign association

data.promoter_campaigns.campaign_id

integer

ID of the campaign

data.promoter_campaigns.promoter_id

integer

ID of the promoter

data.promoter_campaigns.state

enum<string>

State of the promoter in this campaign

Available options:

pending,

accepted,

rejected,

blocked,

inactive,

not_set

data.promoter_campaigns.created_at

string<date-time>

When the promoter was added to the campaign

data.promoter_campaigns.campaign

object

Show child attributes

data.promoter_campaigns.campaign.id

integer

ID of the campaign

data.promoter_campaigns.campaign.name

string

Name of the campaign

data.promoter_campaigns.campaign.color

string

Color code associated with the campaign

data.promoter_campaigns.coupon

string

Coupon code for this campaign

data.promoter_campaigns.ref_token

string

Referral token for this campaign

data.promoter_campaigns.ref_link

string

Referral link for this campaign

API Documentation

Batch Processes

Tracking Api

Referrals

Promoters

Promoter Campaigns

Commissions

Promo Codes

Payouts

Reports

Get available promoters

Authorizations

Headers

Query Parameters

Response