GET
/
referrals
Get available referrals
curl --request GET \
  --url https://v2.firstpromoter.com/api/v2/company/referrals \
  --header 'Account-ID: <account-id>' \
  --header 'Authorization: Bearer <token>'
[
  {
    "id": 123,
    "email": "[email protected]",
    "uid": "<string>",
    "state": "subscribed",
    "metadata": {},
    "entry_source": "api",
    "created_at": "2023-11-07T05:31:56Z",
    "customer_since": "2023-11-07T05:31:56Z",
    "promoter_campaign": {
      "id": 123,
      "campaign_id": 123,
      "promoter_id": 123,
      "created_at": "2023-11-07T05:31:56Z",
      "promoter": {
        "id": 123,
        "email": "[email protected]",
        "name": "<string>"
      },
      "campaign": {
        "id": 123,
        "name": "<string>",
        "color": "<string>"
      }
    },
    "fraud_check": "no_suspicion",
    "created_by_user_email": "[email protected]"
  }
]

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

Query Parameters

​
q
string

Search params. Searches by email, uid, username, website

​
ids[]
integer[]

Array of referral ids to get

​
filters[type]
enum<string>

Filter the referrals by type (lead or customer)

Available options:
lead,
customer
​
filters[promoter_id]
string

Filter the referrals by a promoter id

​
filters[state]
enum<string>

Filter the referrals by state

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

Response

List of referrals

​
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 result of the referral

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