List 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",
      "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
}

{
  "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",
      "affiliate": {
        "id": "aff_456def",
        "name": "John Doe",
        "email": "john@example.com",
        "tracking_id": "PARTNER123",
        "source": "api",
        "partnership_status": "APPROVED",
        "onboarding_completed": true,
        "program_id": "prg_789ghi",
        "group_id": null,
        "created_at": "2024-01-15T10:30:00Z"
      }
    }
  ],
  "has_more": true
}

GET

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",
      "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
}

{
  "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",
      "affiliate": {
        "id": "aff_456def",
        "name": "John Doe",
        "email": "john@example.com",
        "tracking_id": "PARTNER123",
        "source": "api",
        "partnership_status": "APPROVED",
        "onboarding_completed": true,
        "program_id": "prg_789ghi",
        "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 responses

array

Array of referral objects. Each referral object has the same structure as the single referral response (see Get Referral endpoint).

Show Data Object Properties

string

Unique identifier for the referral

string

The affiliate ID who referred this customer

string

The affiliate program ID

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, rejected

string | 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",
      "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
}

{
  "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",
      "affiliate": {
        "id": "aff_456def",
        "name": "John Doe",
        "email": "john@example.com",
        "tracking_id": "PARTNER123",
        "source": "api",
        "partnership_status": "APPROVED",
        "onboarding_completed": true,
        "program_id": "prg_789ghi",
        "group_id": null,
        "created_at": "2024-01-15T10:30:00Z"
      }
    }
  ],
  "has_more": true
}

Getting Started

Guide

Core Resources

Program Management

Marketplace

Query Parameters

Response

​Query Parameters

​Response

Query Parameters

Response