Sign in

v1

latestOpenAPI 3.0.02026-07-264731126.7 KB
Referrals

Update referral

Update a specific referral. The id can be a referral ID, email, uid, or username when used with the find_by parameter in the request body. <Tip>HTTP Request <br/>PUT https://api.firstpromoter.com/api/v2/company/referrals/{id}</Tip>

put/referrals/{id}

Path parameters

idstring required

ID of the referral

Headers

Account-IDstring required

Account id. You can find your Account ID on Your FirstPromoter Dashboard. Navigate to Settings → Integrations

Request body

emailstring email

Email address of the referral, this is required if the uid is null

uidstring

UID of the referral, this is required if the email is null

usernamestring

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.

promoter_campaign_idinteger

Promoter campaign ID, you can obtain this for each promoter from the promoters endpoint. It is the id that pairs a promoter to a campaign. Not the campaign id.

find_by'email' | 'uid' | 'username'

Find by attribute. Required when id parameter is an email, uid, or username instead of an ID.

Your request should follow the format https://api.firstpromoter.com/api/v2/company/referrals/{email or uid or username}

fraud_check'no_suspicion' | 'same_ip_suspicion' | 'same_promoter_email' | 'ad_source'

Sets or clears the fraud check flag on the referral.

  • no_suspicion — clears the flag and marks the referral as manually reviewed. Once cleared this way, automatic fraud detection will not re-flag the referral.
  • same_ip_suspicion — flags the referral because it shares an IP address with the promoter.
  • same_promoter_email — flags the referral because its email matches the promoter's email.
  • ad_source — flags the referral because it arrived via a paid ad click.

You cannot set the same value that is already set unless the referral was previously cleared with no_suspicion.

Example request

{
  "split_details": [
    {
      "promoter_campaign_id": 1002,
      "percentage": 25
    },
    {
      "promoter_campaign_id": 1003,
      "percentage": 30
    }
  ]
}

Response

Referral updated successfully

idinteger

Id of the referral

emailstring email

Email address of the referral

uidstring

uid of the referral

state'subscribed' | 'signup' | 'active' | 'cancelled' | 'refunded' | 'denied' | 'pending' | 'moved'

State of the referral

metadataobject

Additional metadata of the referral

entry_source'api' | 'coupon' | 'cookie' | 'manual_admin' | 'manual_affiliate'

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.

created_atstring date-time

Date and time when the referral was created

customer_sincestring date-time nullable

Date and time when the referral became a customer

fraud_check'no_suspicion' | 'same_ip_suspicion' | 'same_promoter_email' | 'ad_source'

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.

created_by_user_emailstring email nullable

Email address of the user who created the referral

usernamestring nullable

Username chosen by the referral

first_namestring nullable
last_namestring nullable
websitestring nullable
commentstring nullable

Internal note or comment on this referral

is_expiredboolean

Whether the referral has expired

Example response

{
  "promoter_campaign": {
    "promoter": {
      "id": 3920164,
      "status": "active",
      "email": "peluwydo@mailinator.com",
      "created_at": "2022-04-26T15:28:24.800Z",
      "temp_password": "xxxxxxxxxx",
      "default_promotion_id": 4210919,
      "pref": "db1znwe",
      "default_ref_id": "8yi2epelut",
      "note": "This is a note",
      "parent_promoter_id": 577918,
      "earnings_balance": {
        "cash": 50744
      },
      "current_balance": {
        "cash": 20044
      },
      "paid_balance": {
        "cash": 30700
      },
      "auth_token": "xxxxxxxxxxxxxx"
    }
  }
}