> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firstpromoter.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
**HTTP Request**
`PUT https://api.firstpromoter.com/api/v2/company/referrals/{id}`
## OpenAPI
````yaml openapi-v2-referrals put /referrals/{id}
openapi: 3.0.0
info:
title: FirstPromoter Admin API
version: 1.0.0
description: Admin API endpoints for managing referrals in FirstPromoter
servers:
- url: https://api.firstpromoter.com/api/v2/company
description: Production server
security:
- BearerAuth: []
paths:
/referrals/{id}:
put:
tags:
- Referrals
summary: Update referral
description: >-
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}`
parameters:
- $ref: '#/components/parameters/AccountId'
- in: path
name: id
required: true
schema:
type: string
description: ID of the referral
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
email:
type: string
format: email
description: >-
Email address of the referral, this is required if the uid
is null
uid:
type: string
description: UID of the referral, this is required if the email is null
username:
type: string
description: |-
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:
type: integer
description: >-
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:
type: string
enum:
- email
- uid
- username
description: >-
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}`
split_details:
type: array
description: >-
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.
items:
type: object
required:
- promoter_campaign_id
- percentage
properties:
promoter_campaign_id:
type: integer
description: >-
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:
type: integer
description: >-
The percentage of each commission this promoter
receives. Must be between 0 and 100. The sum across
all split entries must not exceed 100.
example:
- promoter_campaign_id: 1002
percentage: 25
- promoter_campaign_id: 1003
percentage: 30
responses:
'200':
description: Referral updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Referral'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not found
components:
parameters:
AccountId:
name: Account-ID
in: header
required: true
description: >-
Account id. You can find your Account ID on Your FirstPromoter
Dashboard. Navigate to Settings → Integrations
schema:
type: string
schemas:
Referral:
type: object
properties:
id:
type: integer
description: Id of the referral
email:
type: string
format: email
description: Email address of the referral
uid:
type: string
description: uid of the referral
state:
type: string
enum:
- subscribed
- signup
- active
- cancelled
- refunded
- denied
- pending
- moved
description: State of the referral
metadata:
type: object
description: Additional metadata of the referral
entry_source:
type: string
enum:
- api
- coupon
- cookie
- manual_admin
- manual_affiliate
description: >-
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:
type: string
format: date-time
description: Date and time when the referral was created
customer_since:
type: string
format: date-time
nullable: true
description: Date and time when the referral became a customer
promoter_campaign:
$ref: '#/components/schemas/PromoterCampaign'
fraud_check:
type: string
enum:
- no_suspicion
- same_ip_suspicion
- same_promoter_email
- ad_source
description: Fraud check result of the referral
created_by_user_email:
type: string
format: email
nullable: true
description: Email address of the user who created the referral
username:
type: string
nullable: true
description: Username chosen by the referral
split_details:
type: array
nullable: true
description: >-
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.
items:
type: object
properties:
promoter_campaign_id:
type: integer
description: The ID of the split partner's campaign enrollment
promoter_id:
type: integer
description: The ID of the split partner (promoter)
percentage:
type: integer
description: The percentage of each commission this promoter receives
first_name:
type: string
nullable: true
last_name:
type: string
nullable: true
website:
type: string
nullable: true
comment:
type: string
nullable: true
description: Internal note or comment on this referral
is_expired:
type: boolean
description: Whether the referral has expired
PromoterCampaign:
type: object
properties:
id:
type: integer
description: Id of the promoter campaign
campaign_id:
type: integer
description: Id of the campaign
promoter_id:
type: integer
description: Id of the promoter
created_at:
type: string
format: date-time
description: Date and time when the promoter campaign was created
promoter:
$ref: '#/components/schemas/Promoter'
campaign:
$ref: '#/components/schemas/Campaign'
Promoter:
type: object
properties:
id:
type: integer
description: Id of the promoter
email:
type: string
format: email
description: Email address of the promoter
name:
type: string
description: Name of the promoter
Campaign:
type: object
properties:
id:
type: integer
description: Id of the campaign
name:
type: string
description: Name of the campaign
color:
type: string
nullable: true
description: Color assigned to the campaign
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
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
````