--- title: "Update referral" method: PUT path: "/referrals/{id}" tags: ["Referrals"] --- # Update referral `PUT /referrals/{id}` 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. **HTTP Request**
`PUT https://api.firstpromoter.com/api/v2/company/referrals/{id}` ## Path parameters - `id` string, required ## Headers - `Account-ID` string, required ## Request body - object - `email` string, email — Email address of the referral, this is required if the uid is null - `uid` string — UID of the referral, this is required if the email is null - `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. - `promoter_campaign_id` integer — 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`. - `split_details` object[] — Update the commission split for this referral. Pass an array of split partners and their percentages to add or replace splits. Pass an empty array (`[]`) to remove all splits. The primary promoter automatically receives the remainder of the commission after all split percentages are applied. The sum of all percentages must not exceed 100. - `promoter_campaign_id` integer, required — The ID of the split partner's campaign enrollment (`promoter_campaign.id`). This is the ID that links a specific promoter to a specific campaign — not the campaign ID itself. - `percentage` integer, required — The percentage of each commission this promoter receives. Must be between 0 and 100. The sum across all split entries must not exceed 100. ## Response `200` Referral updated successfully - Referral - `id` integer — Id of the referral - `email` string, email — Email address of the referral - `uid` string — uid of the referral - `state` 'subscribed' | 'signup' | 'active' | 'cancelled' | 'refunded' | 'denied' | 'pending' | 'moved' — State of the referral - `metadata` object — 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_at` string, date-time — Date and time when the referral was created - `customer_since` string, date-time, nullable — Date and time when the referral became a customer - `promoter_campaign` PromoterCampaign - `id` integer — Id of the promoter campaign - `campaign_id` integer — Id of the campaign - `promoter_id` integer — Id of the promoter - `created_at` string, date-time — Date and time when the promoter campaign was created - `promoter` Promoter - `id` integer — ID of the promoter - `status` string — Status of the promoter - `cust_id` string - `email` string — Email of the promoter - `created_at` string, date-time — ISO date of when the promoter was created - `temp_password` string, nullable — Temporary password created for the promoter - `default_promotion_id` integer - `pref` string - `default_ref_id` string — Default referral id of the promoter - `note` string, nullable — A note/description of promoter - `w8_form_url` string, nullable — Url of the w8 form - `w9_form_url` string, nullable — Url of the w9 form - `parent_promoter_id` integer — Parent promoter id - `earnings_balance` object — Earning balance of the promoter - `cash` integer - `current_balance` object — Current balance of the promoter - `cash` integer - `paid_balance` object — Paid balance of the promoter - `cash` integer - `auth_token` string — Authentication token generated when the promoter was created - `campaign` Campaign - `id` integer — Id of the campaign - `name` string — Name of the campaign - `color` string, nullable — Color assigned to the campaign - `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_email` string, email, nullable — Email address of the user who created the referral - `username` string, nullable — Username chosen by the referral - `split_details` object[], nullable — 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. - `promoter_campaign_id` integer — The ID of the split partner's campaign enrollment - `promoter_id` integer — The ID of the split partner (promoter) - `percentage` integer — The percentage of each commission this promoter receives - `first_name` string, nullable - `last_name` string, nullable - `website` string, nullable - `comment` string, nullable — Internal note or comment on this referral - `is_expired` boolean — Whether the referral has expired ## Other responses - `401` — Unauthorized - `403` — Forbidden - `404` — Not found --- [API](https://skmtc.net/firstpromoter/apis/firstpromoter-batch-processes-api.md) · [All operations](https://skmtc.net/firstpromoter/apis/firstpromoter-batch-processes-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/firstpromoter/firstpromoter-batch-processes-api/versions/e15f0d026ccf/schema)