Skip to main content
POST
Create referral

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 → 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
promoter_campaign_id
integer
required

The ID of the promoter campaign

email
string<email>

Email address of the referral

uid
string

uid of the referral (This can be your user id from your database)

username
string

Username of the referral.

Note: Reach out to us on support if you need this. It needs to be enabled before you can use it.

split_details
object[]

Distribute the referral's commissions across multiple promoters. Each entry specifies a split partner and the percentage of every commission they receive. The primary promoter (set by the top-level promoter_campaign_id) automatically receives the remainder. The sum of all percentages must not exceed 100.

Example:

Response

Referral created successfully

id
integer

Id of the referral

email
string<email>

Email address of the referral

uid
string

uid of the referral

state
enum<string>

State of the referral

Available options:
subscribed,
signup,
active,
cancelled,
refunded,
denied,
pending,
moved
metadata
object

Additional metadata of the referral

entry_source
enum<string>

Entry source of the referral. This shows where the referral was captured from. Cookie is set if the referral was captured using the tid cookie, Coupon is for when the referral is captured via a coupon code. Manual admin is for when the referral is added manually by an admin. Manual affiliate is for when the referral is added manually by an affiliate.

Available options:
api,
coupon,
cookie,
manual_admin,
manual_affiliate
created_at
string<date-time>

Date and time when the referral was created

customer_since
string<date-time> | null

Date and time when the referral became a customer

promoter_campaign
object
fraud_check
enum<string>

Fraud check (suspicion) status of the referral. no_suspicion means the referral is clean or was manually cleared. same_ip_suspicion means the referral shares an IP with the promoter. same_promoter_email means the referral email matches the promoter email. ad_source means the referral arrived via a paid ad click.

Available options:
no_suspicion,
same_ip_suspicion,
same_promoter_email,
ad_source
created_by_user_email
string<email> | null

Email address of the user who created the referral

username
string | null

Username chosen by the referral

split_details
object[] | null

The commission split configuration for this referral. Each entry represents a split partner. The primary promoter (the referral owner) receives the remainder of the commission after all split percentages are applied.

first_name
string | null
last_name
string | null
website
string | null
comment
string | null

Internal note or comment on this referral

is_expired
boolean

Whether the referral has expired