API Integration

FirstPromoter Docs

Turn Affiliate Marketing into Your Competitive Advantage

Set up and manage your own affiliate program, no matter how simple or complex your affiliate scheme is.

How FirstPromoter works

Start building your awesome affiliate or referral program in minutes.

Quickstart

This is a reference document for all the methods available in FirstPromoters's browswer-side JavaScript Library, fpr.js

FirstPromoter JavaScript Library (fpr.js)

Advanced use cases & examples

List of concepts and key terminologies used in the documentation

Concepts & Key Terminologies

Stripe

Chargebee

Recurly

Paddle

Braintree

Highlevel

Adding FirstPromoter to your ClickFunnels website

ClickFunnels

Adding FirstPromoter to your Ghost Website

Ghost

Kajabi

ThriveCart

Samcart

Kartra

Adding FirstPromoter to your DropFunnels website

DropFunnels

Calendly

Kickpages

Thinkific

Use our Javascript option to track clicks and sign-ups

JavaScript Tracking

Adding FirstPromoter to your Django website

Django

Adding FirstPromoter to your custom PHP website

Adding FirstPromoter to your Rails website

Ruby on rails

Stripe Checkout

Paddle Checkout

Setting up your Main tracking script in Google Tag Manager (GTM)

Google Tag Manager

Overview

Lead Signup

Reward Created

New Customer

Promoter Accepted

Fulfilment Pending

This is the public API documentation for FirstPromoter.

Introduction

Authentication

Capture a lead when they sign-up or fill an optin form. This endpoint is used to track leads and sign-ups. It's not for tracking the actual sales and commissions. Sign-ups are tracked as leads in FirstPromoter so when a person referred by the promoter/affiliate signs up, a new referral should be added inside FirstPromoter **(you can see them inside the `Referrals` section as `Leads`)**. <Tip>The recommended way to do this is to grab the `_fprom_tid` **(_fprom_track for accounts created prior to April 2021)** cookie value(which keeps the tracking id and referral identification) on your server and send it along with the sign-up data through the tid parameter. **Alternative:** In some special cases, you can refer sign ups directly to a promoter, by passing the referral id through ref_id parameter. Be careful when using this because the referral id can be modified by the promoter by default, however you can disable that from the campaign configuration page.</Tip><Tip>**HTTP Request** `POST https://firstpromoter.com/api/v1/track/signup`</Tip>

Tracking leads and sign-ups

Assign sales and commissions to your promoters. To track sales and generate commissions correctly, you need to use this API call each time a non-zero amount sale is processed in your system, even if it comes from a recurring charge or one-time charge. <Note>To avoid fraudulent sales, we don't use JS conversion pixels to track sales, which are very unreliable and can be easily faked. Instead, we use server-side tracking for all sales to ensure that a sale is tracked only when you actually receive money in your billing account. To maintain the same standards with the API, we recommend making the sale API call (this call) only when you receive confirmation of the sale from your billing provider, such as from a webhook, an IPN, or a success response from an API charge call. You just need to pass the sale amount (before taxes) and we'll take care of the rest. The commissions/rewards will be calculated based on that amount and the plan ID, in case you use the plan-level rewards feature.</Note> Using email or UID parameters, we identify the lead/customer who generated the sale, which also helps us determine the promoter who owns the reward/commission. The lead is added to our system either by the client signup tracking script when the user signs up or by calling the signup API endpoint. There is also the option to bypass the signup tracking by using TID or ref_id parameters, which will create the lead and assign the sale in one go. **If we don't find the lead in our system, it means that the sale is not a referral sale and you'll get a 204 response. You don't have to identify which sale is from referrals and which is not; we'll take care of that.** <Tip>**For zero-decimal** currencies like `JPY`, `amount` and `mrr` parameters should be sent as **whole values**. **For other currencies**, `amount` and `mrr` parameter values should be in cents, i.e., you will need to **multiply the value by 100** before sending the request.</Tip><Tip>**HTTP Request** `POST https://firstpromoter.com/api/v1/track/sale`</Tip>

Tracking sales and commissions

The refund call is similar to the sale call. It works the same way, except that it generates negative commissions.<Tip>**HTTP Request** `POST https://firstpromoter.com/api/v1/track/refund`</Tip>

Tracking refunds and negative commissions

This call will mark the customer as cancelled and will decrease the MRR generated by him/her.<Tip>**HTTP Request** `POST https://firstpromoter.com/api/v1/track/cancellation`</Tip>

Tracking cancellations

Use this to update a lead/customer details from FirstPromoter using the API. You can find the lead either by `id` , `uid` or `email` <Tip>**HTTP Request** `PUT https://firstpromoter.com/api/v1/leads/update`</Tip>

Modify existing lead/customer

With this endpoint you can list all the leads and customers assigned to a promotion, promoter, campaign or entire account using the API. <Note>Pagination details are held on response headers. Add `--include` option on `curl` request to see the pagination details format and links to next pages.</Note><Tip>**HTTP Request** `GET https://firstpromoter.com/api/v1/leads/list`</Tip>

List leads/customers

Show the lead/customer details from FirstPromoter using the API. You can find the referral either by `id` , `uid` or `email` <Tip>**HTTP Request** `GET https://firstpromoter.com/api/v1/leads/show`</Tip>

Show leads and customers details

Remove a lead/customer from FirstPromoter using the API. You can find the referral either by `id` , `uid` or `email`. <Tip>**HTTP Request** `DELETE https://firstpromoter.com/api/v1/leads/delete`</Tip>

Delete lead/customer

Use this endpoint to create new promoters using the API. The response will return the newly added promoter as JSON. Probably the most important value from the response is `auth_token`, which is a unique key auto-generated on creation and can be used to automatically log in your promoters to their dashboard. [Learn more](https://help.firstpromoter.com/faq/how-to-embed-the-promoter-dashboard-inside-your-website-and-log-your-users-in-automatically). <Note> If this call is successful and you enabled `Promoter sign up accepted` emails for the campaign, it will start sending emails to the promoter. To skip the emails, set the `skip_email_notification` parameter to `true`</Note><Tip>**HTTP Request** `POST https://firstpromoter.com/api/v1/promoters/create`</Tip>

Create a new promoter

You can identify promoters by: `id`, `cust_id`, `auth_token` or `ref_id`(referral id). You need to pass at least one of these parameters.

Modify existing promoter

Use this endpoint to list your promoters using the API. The response will return the promoters as JSON array.<Note> Pagination details are held on response headers. Add `--include` option on `curl` request to see the pagination details format and links to next pages.</Note><Tip>**HTTP Request** `GET https://firstpromoter.com/api/v1/promoters/list`</Tip>

List promoters

You can identify promoters by: `id` , `cust_id` , `auth_token` , `promoter_email` or `ref_id`(referral id). You need to pass at least one of these parameters.<Tip>**HTTP Request** `GET https://firstpromoter.com/api/v1/promoters/show`</Tip>

Show promoter details and balance

This endpoint will change the promoter's campaign to another one, keeping the referral ID the same (the affiliate won’t need to update the referral link). It serves the same function as moving the promoter to another campaign from the UI.More details on how it works can be found [here](https://help.firstpromoter.com/en/articles/2509650-moving-promoters-from-one-campaign-to-another). You can identify promoters by: `id`, `cust_id`, `auth_token`, `promoter_email` or `ref_id`(referral id).<Tip> **HTTP Request** `POST https://firstpromoter.com/api/v1/promoters/move_to_campaign` </Tip>

Move/switch a promoter from one campaign to another

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). <Tip> **HTTP Request** `POST https://firstpromoter.com/api/v1/promoters/add_to_campaign` </Tip>

Add a promoter to a campaign

Resetting the authentication token (`auth_token`), which is used to automatically sign in your promoters (if you use this feature), is not required but can enhance the security of the promoter dashboard. You can set up a cron job to call the API endpoint and store the new auth_token from the response. You can identify promoters by id, cust_id, or auth_token; only one is required.<Tip> **HTTP Request** `PUT https://firstpromoter.com/api/v1/promoters/refresh_token` </Tip>

Reset promoter's authentication token

You can identify promoters by: `id` , `cust_id` , `auth_token` , `promoter_email` or `ref_id`(referral id). You need to pass at least one of these parameters.<Tip>**HTTP Request** `DELETE https://firstpromoter.com/api/v1/promoters/delete`</Tip>

Delete a promoter

With this endpoint, you can assign a commission generated by a referral, and it will be recorded to the promoter who referred the lead/customer. You can find the referral by lead_id, email, or UID. If the reward/commission is not generated by a lead/customer, you can assign it directly to a promoter through its promotion. You can find the promotion by `promotion_id` or `ref_id`. <Note>Note: To assign rewards/commission for sales via the API use the Tracking API</Note><Note>If this call is successful and you enabled 'Promoter gets a new commission/reward' emails for the campaign, it will send emails to the promoter. To skip the emails, set the `skip_email_notification` parameter to `true`</Note><Tip>**HTTP Request** `POST https://firstpromoter.com/api/v1/rewards/create`</Tip>

Create new reward

With this endpoint you can list all rewards and commissions assigned to a promotion, promoter, campaign or entire account using the API.<Note>Pagination details are held on response headers. Add `--include` option on `curl` request to see the pagination details format and links to next pages.</Note><Tip>**HTTP Request** `GET https://firstpromoter.com/api/v1/leads/list`</Tip>

List rewards and commissions

You can use this endpoint to change the status of a reward or commission. You can identify the reward or commission by its id or the id of the event that generated the reward.<Note>For Stripe, Recurly and Chargebee subscription the `event_id` value is the Invoice id, for Stripe one time charges is the charge id.</Note><Tip>**HTTP Request** `PUT https://firstpromoter.com/api/v1/rewards/update`</Tip>

Update a reward or commission

With this endpoint, you can list all payouts for a promoter, a campaign, or the entire account using the API. <Tip>**HTTP Request** `GET https://firstpromoter.com/api/v1/payouts/list`</Tip>

List payouts

This call allows you to create a payout for a specific promoter for the entire unpaid amount.

Create a new payout

This call allows you to change the status of the payout. For example, you can mark the payout as completed once it has been paid.

Change payouts status

<Note>With this endpoint you can get an overview across all your campaigns and promoters. Data is updated every `15 minutes`</Note><Tip>**HTTP Request** `GET https://firstpromoter.com/api/v1/reports/overview` </Tip>

Overview reports

<Note>With this endpoint you can get the report data grouped by campaigns. Data is updated every `15 minutes`</Note><Tip>**HTTP Request** `GET https://firstpromoter.com/api/v1/reports/campaigns` </Tip>

Campaign reports

<Note>With this endpoint you can get the report data grouped by promoters. Data is updated once a day, at midnight. This endpoint supports pagination, similar with other endpoints, by passing `page` param. If you want to iterate through all promoters, you **must start with** `page=1` and continue to next pages based on header pagination links from the response. The paginated promoters are always ordered by the total revenue made (not the revenue brought during the selected period). If **page param is ommited**, we'll return **top 50 promoters** by **revenue amount** on the selected period. You can get the **top 50 promoters** sorted by a different metric using the `top_50` parameter.</Note><Tip> **HTTP Request** `GET https://firstpromoter.com/api/v1/reports/promoters`</Tip>

Promoter reports

This is the public API documentation for FirstPromoter V2.

Get available referrals 
 <Tip>**HTTP Request** `GET https://firstpromoter.com/api/v2/company/referrals`</Tip>

Get available referrals

Create a new referral 
 <Tip>**HTTP Request** `POST https://firstpromoter.com/api/v2/company/referrals`</Tip>

Create referral

Get a specific referral 
 <Tip>**HTTP Request** `GET https://firstpromoter.com/api/v2/company/referrals/{id}`</Tip>

Get referral

Update a specific referral 
 <Tip>**HTTP Request** `PUT https://firstpromoter.com/api/v2/company/referrals/{id}`</Tip>

Update referral

With this endpoint you can move referrals to another promoter. 
 <Tip>**HTTP Request** `POST https://firstpromoter.com/api/v2/company/referrals/move_to_promoter`</Tip>

Move referrals to promoter

With this endpoint you can delete referrals. 
 <Tip>**HTTP Request** `DELETE https://firstpromoter.com/api/v2/company/referrals/destroy`</Tip>

Delete referrals

With this endpoint you can list all promoters. 
 <Tip>**HTTP Request** `GET https://firstpromoter.com/api/v2/company/promoters`</Tip>

Get available promoters

With this endpoint you can create a promoter. 
 <Tip>**HTTP Request** `POST https://firstpromoter.com/api/v2/company/promoters`</Tip>

Create promoter

With this endpoint you can get the details of a promoter. 
 <Tip>**HTTP Request** `GET https://firstpromoter.com/api/v2/company/promoters/{id}`</Tip>

Get promoter details

With this endpoint you can update a promoter. 
 <Tip>**HTTP Request** `PUT https://firstpromoter.com/api/v2/company/promoters/{id}`</Tip>

Update promoter

With this endpoint you can get the data used for charts.<Tip>**HTTP Request** `GET https://firstpromoter.com/api/v2/company/promoters/{id}/chart_data`</Tip>

Get data used for chart

With this endpoint you can accept promoters. 
 <Tip>**HTTP Request** `POST https://firstpromoter.com/api/v2/company/promoters/accept`</Tip>

Accept promoters

With this endpoint you can reject promoters. 
 <Tip>**HTTP Request** `POST https://firstpromoter.com/api/v2/company/promoters/reject`</Tip>

Reject promoters

With this endpoint you can block promoters. 
 <Tip>**HTTP Request** `POST https://firstpromoter.com/api/v2/company/promoters/block`</Tip>

Block promoters

With this endpoint you can archive promoters. 
 <Tip>**HTTP Request** `POST https://firstpromoter.com/api/v2/company/promoters/archive`</Tip>

Archive promoters

With this endpoint you can restore promoters. 
 <Tip>**HTTP Request** `POST https://firstpromoter.com/api/v2/company/promoters/restore`</Tip>

Restore promoters

With this endpoint you can list all rewards and commissions assigned to a promotion, promoter, campaign or entire account using the API. 
 <Tip>**HTTP Request** `GET https://firstpromoter.com/api/v2/company/commissions`</Tip>

Get all commissions

With this endpoint you can create a commission. 
 <Tip>**HTTP Request** `POST https://firstpromoter.com/api/v2/company/commissions`</Tip>

Create a commission

With this endpoint you can update a commission. 
 <Tip>**HTTP Request** `PUT https://firstpromoter.com/api/v2/company/commissions/{id}`</Tip>

Update a commission

With this endpoint you can approve commissions. 
 <Tip>**HTTP Request** `POST https://firstpromoter.com/api/v2/company/commissions/approve`</Tip>

Approve commissions

With this endpoint you can deny commissions. 
 <Tip>**HTTP Request** `POST https://firstpromoter.com/api/v2/company/commissions/deny`</Tip>

Deny commissions

With this endpoint you can mark commissions payout as fulfilled. 
 <Tip>**HTTP Request** `POST https://firstpromoter.com/api/v2/company/commissions/mark_fulfilled`</Tip>

Mark commissions payout as fulfilled

With this endpoint you can mark commissions payout as unfulfilled. 
 <Tip>**HTTP Request** `POST https://firstpromoter.com/api/v2/company/commissions/mark_unfulfilled`</Tip>

Mark commissions payout as unfulfilled

Create promo code

Can not be updated if archived and ext_id present and promoter can manage tracking coupons.

Update promo code by id

Archive promo code by id only if promo code is created by current promoter.

Archive promo code by id

With this endpoint you can list all payouts. 
 <Tip>**HTTP Request** `GET https://firstpromoter.com/api/v2/company/payouts`</Tip>

Get all payouts

This endpoint returns statistics about payouts. 
 <Tip>**HTTP Request** `GET https://firstpromoter.com/api/v2/company/payouts/stats`</Tip>

Get payout stats

This endpoint returns statistics about due payouts. 
 <Tip>**HTTP Request** `GET https://firstpromoter.com/api/v2/company/payouts/due_stats`</Tip>

Get due payout stats

This endpoint returns all payouts but grouped by promoters. 
 <Tip>**HTTP Request** `GET https://firstpromoter.com/api/v2/company/payouts/group_by_promoters`</Tip>

Get all payouts grouped by promoters

With this endpoint you can get the report data grouped by campaigns.<Tip>**HTTP Request** `GET https://firstpromoter.com/api/v2/company/reports/campaigns`</Tip>

Get reports for campaigns

Get reports for overview 
 <Tip>**HTTP Request** `GET https://firstpromoter.com/api/v2/company/reports/overview`</Tip>

Get reports for overview

With this endpoint you can get the report data grouped by promoters.<Tip>**HTTP Request** `GET https://firstpromoter.com/api/v2/company/reports/promoters`</Tip>

Get reports for promoters

With this endpoint you can get the report data grouped by URLs.<Tip>**HTTP Request** `GET https://firstpromoter.com/api/v2/company/reports/urls`</Tip>

Get reports for URLs

With this endpoint you can get the report data grouped by traffic sources. 
 <Tip>**HTTP Request** `GET https://firstpromoter.com/api/v2/company/reports/traffic_sources`</Tip>

Overview

How to Guides

Scripts

Integration Options

Webhooks

API Integration