Skip to main content
GET
/
v1
/
referrals
curl -X GET "https://api.affonso.io/v1/referrals?limit=10&status=customer" \
  -H "Authorization: Bearer sk_live_your_api_key"

{
  "success": true,
  "data": [
    {
      "id": "ref_abc123",
      "affiliate_id": "aff_456def",
      "program_id": "prg_789ghi",
      "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
}

​
Query Parameters

​
limit
integer
default:"10"
Number of results per page. Minimum value is 1, maximum value is 100. Default is 10.
​
starting_after
string
Cursor for pagination. Use the id of the last item from the previous page to get the next page.
​
ending_before
string
Cursor for pagination. Use the id of the first item from the current page to get the previous page.
​
affiliate_id
string
Filter referrals by affiliate ID. Only returns referrals for the specified affiliate.
​
external_user_id
string
Filter referrals by your external user ID. Useful when you store your own application user ID on the referral.
​
order
string
default:"desc"
Sort order. Valid values: asc, desc. Defaults to desc (newest first).
​
status
string
Filter referrals by status. Valid values: lead, trialing, customer, active, canceled, rejected. Note: click status is excluded from this endpoint.
​
created_gte
string
Filter referrals created on or after this date. ISO 8601 date-time format (e.g., 2024-01-01T00:00:00Z).
​
created_lte
string
Filter referrals created on or before this date. ISO 8601 date-time format (e.g., 2024-12-31T23:59:59Z).
​
expand
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.
​
success
boolean
Always true for successful responses
​
data
array
Array of referral objects. Each referral object has the same structure as the single referral response (see Get Referral endpoint).
​
has_more
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"

{
  "success": true,
  "data": [
    {
      "id": "ref_abc123",
      "affiliate_id": "aff_456def",
      "program_id": "prg_789ghi",
      "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
}