curl -X GET "https://api.affonso.io/v1/referrals?limit=10&status=customer" \
-H "Authorization: Bearer sk_live_your_api_key"
curl -X GET "https://api.affonso.io/v1/referrals?external_user_id=user_42" \
-H "Authorization: Bearer sk_live_your_api_key"
curl -X GET "https://api.affonso.io/v1/referrals?limit=10&expand=affiliate" \
-H "Authorization: Bearer sk_live_your_api_key"
{
"success": true,
"data": [
{
"id": "ref_abc123",
"affiliate_id": "aff_456def",
"email": "customer@example.com",
"customer_id": "cust_123",
"external_user_id": "user_42",
"subscription_id": null,
"status": "customer",
"name": "John Doe",
"metadata": {
"plan": "enterprise"
},
"created_at": "2024-01-20T15:30:00Z",
"converted_at": "2024-01-20T15:30:00Z"
}
],
"has_more": true
}
{
"success": true,
"data": [
{
"id": "ref_abc123",
"affiliate_id": "aff_456def",
"email": "customer@example.com",
"customer_id": "cust_123",
"external_user_id": "user_42",
"subscription_id": null,
"status": "customer",
"name": "John Doe",
"metadata": {
"plan": "enterprise"
},
"created_at": "2024-01-20T15:30:00Z",
"converted_at": "2024-01-20T15:30:00Z",
"affiliate": {
"id": "aff_456def",
"name": "John Doe",
"email": "john@example.com",
"tracking_id": "PARTNER123",
"source": "api",
"partnership_status": "APPROVED",
"onboarding_completed": true,
"group_id": null,
"created_at": "2024-01-15T10:30:00Z"
}
}
],
"has_more": true
}
Referrals
List Referrals
Get a cursor-paginated list of all referrals with optional filtering and expansion
GET
/
v1
/
referrals
curl -X GET "https://api.affonso.io/v1/referrals?limit=10&status=customer" \
-H "Authorization: Bearer sk_live_your_api_key"
curl -X GET "https://api.affonso.io/v1/referrals?external_user_id=user_42" \
-H "Authorization: Bearer sk_live_your_api_key"
curl -X GET "https://api.affonso.io/v1/referrals?limit=10&expand=affiliate" \
-H "Authorization: Bearer sk_live_your_api_key"
{
"success": true,
"data": [
{
"id": "ref_abc123",
"affiliate_id": "aff_456def",
"email": "customer@example.com",
"customer_id": "cust_123",
"external_user_id": "user_42",
"subscription_id": null,
"status": "customer",
"name": "John Doe",
"metadata": {
"plan": "enterprise"
},
"created_at": "2024-01-20T15:30:00Z",
"converted_at": "2024-01-20T15:30:00Z"
}
],
"has_more": true
}
{
"success": true,
"data": [
{
"id": "ref_abc123",
"affiliate_id": "aff_456def",
"email": "customer@example.com",
"customer_id": "cust_123",
"external_user_id": "user_42",
"subscription_id": null,
"status": "customer",
"name": "John Doe",
"metadata": {
"plan": "enterprise"
},
"created_at": "2024-01-20T15:30:00Z",
"converted_at": "2024-01-20T15:30:00Z",
"affiliate": {
"id": "aff_456def",
"name": "John Doe",
"email": "john@example.com",
"tracking_id": "PARTNER123",
"source": "api",
"partnership_status": "APPROVED",
"onboarding_completed": true,
"group_id": null,
"created_at": "2024-01-15T10:30:00Z"
}
}
],
"has_more": true
}
Query Parameters
integer
default:"10"
Number of results per page. Minimum value is 1, maximum value is 100. Default is 10.
string
Cursor for pagination. Use the
id of the last item from the previous page to get the next page.string
Cursor for pagination. Use the
id of the first item from the current page to get the previous page.string
Filter referrals by affiliate ID. Only returns referrals for the specified affiliate.
string
Filter referrals by your external user ID. Useful when you store your own application user ID on the referral.
string
default:"desc"
Sort order. Valid values:
asc, desc. Defaults to desc (newest first).string
Filter referrals by status. Valid values:
lead, trialing, customer, active, canceled, rejected. Note: click status is excluded from this endpoint.string
Filter referrals created on or after this date. ISO 8601 date-time format (e.g.,
2024-01-01T00:00:00Z).string
Filter referrals created on or before this date. ISO 8601 date-time format (e.g.,
2024-12-31T23:59:59Z).string
Comma-separated list of related data to include. Valid values:
affiliate. Example: expand=affiliate.Response
The response includes a cursor-paginated list of referrals.boolean
Always
true for successful responsesarray
Array of referral objects. Each referral object has the same structure as the single referral response (see Get Referral endpoint).
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)boolean
Whether there are more results available
curl -X GET "https://api.affonso.io/v1/referrals?limit=10&status=customer" \
-H "Authorization: Bearer sk_live_your_api_key"
curl -X GET "https://api.affonso.io/v1/referrals?external_user_id=user_42" \
-H "Authorization: Bearer sk_live_your_api_key"
curl -X GET "https://api.affonso.io/v1/referrals?limit=10&expand=affiliate" \
-H "Authorization: Bearer sk_live_your_api_key"
{
"success": true,
"data": [
{
"id": "ref_abc123",
"affiliate_id": "aff_456def",
"email": "customer@example.com",
"customer_id": "cust_123",
"external_user_id": "user_42",
"subscription_id": null,
"status": "customer",
"name": "John Doe",
"metadata": {
"plan": "enterprise"
},
"created_at": "2024-01-20T15:30:00Z",
"converted_at": "2024-01-20T15:30:00Z"
}
],
"has_more": true
}
{
"success": true,
"data": [
{
"id": "ref_abc123",
"affiliate_id": "aff_456def",
"email": "customer@example.com",
"customer_id": "cust_123",
"external_user_id": "user_42",
"subscription_id": null,
"status": "customer",
"name": "John Doe",
"metadata": {
"plan": "enterprise"
},
"created_at": "2024-01-20T15:30:00Z",
"converted_at": "2024-01-20T15:30:00Z",
"affiliate": {
"id": "aff_456def",
"name": "John Doe",
"email": "john@example.com",
"tracking_id": "PARTNER123",
"source": "api",
"partnership_status": "APPROVED",
"onboarding_completed": true,
"group_id": null,
"created_at": "2024-01-15T10:30:00Z"
}
}
],
"has_more": true
}
Was this page helpful?