List promoters

cURL

curl --request GET \
  --url https://firstpromoter.com/api/v1/promoters/list \
  --header 'X-API-KEY: <api-key>'

[
  {
    "id": 8815216,
    "status": "active",
    "cust_id": null,
    "email": "[email protected]",
    "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": "[email protected]",
    "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
      }
    ]
  }
]

GET

list

cURL

curl --request GET \
  --url https://firstpromoter.com/api/v1/promoters/list \
  --header 'X-API-KEY: <api-key>'

[
  {
    "id": 8815216,
    "status": "active",
    "cust_id": null,
    "email": "[email protected]",
    "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": "[email protected]",
    "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
      }
    ]
  }
]

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.

Authorizations

X-API-KEY

string

header

required

Query Parameters

campaign_id

string

List all promoters accepted to a specific campaign.

Response

List Promoters response

integer

The promoter's ID inside FirstPromoter

status

enum<string>

Promoter's status

Available options:

approved,

pending,

denied

cust_id

string

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 scribscibe for FirstPromoter's webhooks.

string

Promoter's email

created_at

string

ISO date string when the promoter signed up

temp_password

string

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.

default_promotion_id

number

Promoter's default promotion id

Example:

128833

pref

string

Promoter's parent referral id.

default_ref_id

string

Promoter's default referral id

note

string

A note/description of promoter

w8_form_url

string

The w8 form url

w9_form_url

string

The w9 form url

parent_promoter_id

string

Parent promoter id

earnings_balance

object

Promoter's earnings balance. This object can contain cash, credits, discount_per

Show child attributes

earnings_balance.cash

integer

The cash earnings

Example:

3000

earnings_balance.credits

integer

The earning credits

Example:

300

earnings_balance.discount_per

integer

The earning discount percentage

Example:

30

current_balance

object

Promoter's current balance. This object can contain cash, credits, discount_per

Show child attributes

current_balance.cash

integer

The current cash balance

Example:

1000

current_balance.credits

integer

The current credits

Example:

200

current_balance.discount_per

integer

The current discount percentage

Example:

15

paid_balance

object

Promoter's paid balance. This object can contain cash, credits, discount_per

Show child attributes

paid_balance.cash

integer

The cash paid

Example:

2000

paid_balance.credits

integer

The credits given

Example:

100

paid_balance.discount_per

integer

The discount percentage given

Example:

15

auth_token

string

Authentication token generated when the promoter was created

profile

object

Show child attributes

profile.first_name

string

Promoter's first name

profile.last_name

string

Promoter's last name

profile.website

string

Promoter's website

profile.company_name

string

Promoter's campany name

profile.phone_number

string

Promoter's phone number

profile.address

string

Promoter's address

profile.vat_id

string

Promoter's vat id

profile.country

string

Promoter's country

profile.paypal_email

string

Promoter's Paypal email address

profile.avatar_url

string

URL of the profile picture promoters can see on their dashboard

profile.description

string

A note/description of promoter

Show child attributes

Promoter's twitter url

Show child attributes

Promoter's youtube url

Show child attributes

Promoter's fackbook url

Show child attributes

Promoter's linkedin url

Show child attributes

Promoter's instagram url

promotions

object[]

Show child attributes

promotions.id

number

ID of the promotion.

promotions.status

string

Current offer status.

promotions.ref_id

string

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

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.

promotions.target_reached_at

object

promotions.promoter_id

number

ID of the promoter/affiliate.

promotions.campaign_id

number

ID of the campaign where the promotion runs.

promotions.referral_link

string

Promoter's referral link

promotions.current_offer

object

Show child attributes

promotions.current_offer.id

number

The reward id

promotions.current_offer.name

string

The reward name

promotions.current_offer.amount

number

The reward amount

promotions.current_offer.unit

string

The reward unit (e.g., 'credits', 'free_months', 'cash').

promotions.current_referral_reward

object

Show child attributes

promotions.current_referral_reward.id

number

promotions.current_referral_reward.amount

number

promotions.current_referral_reward.unit

string

promotions.current_referral_reward.name

string

promotions.current_referral_reward.per_of_sale

number

promotions.current_promotion_reward

object

promotions.current_target_reward

object

promotions.campaign_name

string

promotions.hidden

boolean

promotions.visitors_count

number

promotions.leads_count

number

promotions.customers_count

number

promotions.refunds_count

number

promotions.cancellations_count

number

promotions.sales_count

number

promotions.sales_total

number

promotions.refunds_total

number

promotions.active_customers_count

number

Example:

[
  {
    "id": 8815216,
    "status": "active",
    "cust_id": null,
    "email": "[email protected]",
    "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": "[email protected]",
    "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
      }
    ]
  }
]

Modify existing promoter Show promoter details and balance

⌘I

API Documentation

Tracking

Leads

Promoters

Rewards

Payouts

Reports

Authorizations

Query Parameters

Response