curl -X POST "https://api.affonso.io/v1/referrals" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"affiliate_id": "aff_123abc",
"email": "newcustomer@example.com",
"customer_id": "cust_456",
"status": "customer",
"name": "John Doe",
"metadata": {
"plan": "enterprise",
"source": "webinar"
}
}'
{
"success": true,
"data": {
"id": "ref_abc123",
"affiliate_id": "aff_123abc",
"email": "newcustomer@example.com",
"customer_id": "cust_456",
"external_user_id": null,
"subscription_id": null,
"status": "customer",
"name": "John Doe",
"metadata": {
"plan": "enterprise",
"source": "webinar"
},
"created_at": "2024-01-20T15:30:00Z",
"converted_at": "2024-01-20T15:30:00Z"
}
}
Referrals
Create Referral
Create a new referral or convert an existing click to a referral
POST
/
v1
/
referrals
curl -X POST "https://api.affonso.io/v1/referrals" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"affiliate_id": "aff_123abc",
"email": "newcustomer@example.com",
"customer_id": "cust_456",
"status": "customer",
"name": "John Doe",
"metadata": {
"plan": "enterprise",
"source": "webinar"
}
}'
{
"success": true,
"data": {
"id": "ref_abc123",
"affiliate_id": "aff_123abc",
"email": "newcustomer@example.com",
"customer_id": "cust_456",
"external_user_id": null,
"subscription_id": null,
"status": "customer",
"name": "John Doe",
"metadata": {
"plan": "enterprise",
"source": "webinar"
},
"created_at": "2024-01-20T15:30:00Z",
"converted_at": "2024-01-20T15:30:00Z"
}
}
Body Parameters
string
required
The unique identifier of the affiliate who referred this customer. The affiliate must belong to your team.
string
required
The customer’s email address. Must be a valid email format. If a referral with this email already exists for the program, the request will fail with a conflict error.
string
Your internal customer ID or identifier. Used to link the referral to a customer in your system.
string
Your internal subscription ID if this referral is for a subscription. Used to track subscription-based referrals.
string
Optional click ID to convert an existing click to a referral. If provided, the click will be updated to a referral with the specified status. The click must belong to your team and have status
CLICK.string
default:"lead"
The initial referral status. Valid values:
lead, trialing, customer, active, canceled, rejected. Defaults to lead. If set to any value other than lead, converted_at will be automatically set.string
Optional ISO 8601 timestamp to backdate the referral creation. If not provided, uses the current timestamp.
string
The customer’s name. Used to identify the referred customer.
object
Custom key-value data for storing additional information about the referral. You can store any JSON-serializable data here.
Response
The response includes the created referral object.boolean
Always
true for successful responsesobject
The created referral object.
Show Data Object Properties
Show Data Object Properties
string
Unique identifier for the referral
string
The affiliate ID who referred this customer
string | null
The customer’s email address
string | null
Your internal customer ID if provided
string | null
Your external user ID if this referral is linked to a user from your application
string | null
Your internal subscription ID if provided
string
The referral status (lowercase):
lead, trialing, customer, active, canceled, rejectedstring | null
The customer’s name if provided
object | null
Custom key-value data if provided
string
ISO 8601 timestamp of when the referral was created
string | null
ISO 8601 timestamp of when the referral was converted (set when status is not
lead)curl -X POST "https://api.affonso.io/v1/referrals" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"affiliate_id": "aff_123abc",
"email": "newcustomer@example.com",
"customer_id": "cust_456",
"status": "customer",
"name": "John Doe",
"metadata": {
"plan": "enterprise",
"source": "webinar"
}
}'
{
"success": true,
"data": {
"id": "ref_abc123",
"affiliate_id": "aff_123abc",
"email": "newcustomer@example.com",
"customer_id": "cust_456",
"external_user_id": null,
"subscription_id": null,
"status": "customer",
"name": "John Doe",
"metadata": {
"plan": "enterprise",
"source": "webinar"
},
"created_at": "2024-01-20T15:30:00Z",
"converted_at": "2024-01-20T15:30:00Z"
}
}
Was this page helpful?