> ## Documentation Index
> Fetch the complete documentation index at: https://docs.affonso.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Referrals

> Get a cursor-paginated list of all referrals with optional filtering and expansion

## Query Parameters

<ParamField query="limit" type="integer" default="10">
  Number of results per page. Minimum value is 1, maximum value is 100. Default is 10.
</ParamField>

<ParamField query="starting_after" type="string">
  Cursor for pagination. Use the `id` of the last item from the previous page to get the next page.
</ParamField>

<ParamField query="ending_before" type="string">
  Cursor for pagination. Use the `id` of the first item from the current page to get the previous page.
</ParamField>

<ParamField query="affiliate_id" type="string">
  Filter referrals by affiliate ID. Only returns referrals for the specified affiliate.
</ParamField>

<ParamField query="external_user_id" type="string">
  Filter referrals by your external user ID. Useful when you store your own application user ID on the referral.
</ParamField>

<ParamField query="order" type="string" default="desc">
  Sort order. Valid values: `asc`, `desc`. Defaults to `desc` (newest first).
</ParamField>

<ParamField query="status" type="string">
  Filter referrals by status. Valid values: `lead`, `trialing`, `customer`, `active`, `canceled`, `rejected`. Note: `click` status is excluded from this endpoint.
</ParamField>

<ParamField query="created_gte" type="string">
  Filter referrals created on or after this date. ISO 8601 date-time format (e.g., `2024-01-01T00:00:00Z`).
</ParamField>

<ParamField query="created_lte" type="string">
  Filter referrals created on or before this date. ISO 8601 date-time format (e.g., `2024-12-31T23:59:59Z`).
</ParamField>

<ParamField query="expand" type="string">
  Comma-separated list of related data to include. Valid values: `affiliate`. Example: `expand=affiliate`.
</ParamField>

## Response

The response includes a cursor-paginated list of referrals.

<ResponseField name="success" type="boolean">
  Always `true` for successful responses
</ResponseField>

<ResponseField name="data" type="array">
  Array of referral objects. Each referral object has the same structure as the single referral response (see Get Referral endpoint).

  <Expandable title="Data Object Properties">
    <ResponseField name="id" type="string">
      Unique identifier for the referral
    </ResponseField>

    <ResponseField name="affiliate_id" type="string">
      The affiliate ID who referred this customer
    </ResponseField>

    <ResponseField name="program_id" type="string">
      The affiliate program ID
    </ResponseField>

    <ResponseField name="email" type="string | null">
      The customer's email address
    </ResponseField>

    <ResponseField name="customer_id" type="string | null">
      Your internal customer ID if provided
    </ResponseField>

    <ResponseField name="external_user_id" type="string | null">
      Your external user ID if this referral is linked to a user from your application
    </ResponseField>

    <ResponseField name="subscription_id" type="string | null">
      Your internal subscription ID if provided
    </ResponseField>

    <ResponseField name="status" type="string">
      The referral status (lowercase): `lead`, `trialing`, `customer`, `active`, `canceled`, `rejected`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The customer's name if provided
    </ResponseField>

    <ResponseField name="metadata" type="object | null">
      Custom key-value data if provided
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the referral was created
    </ResponseField>

    <ResponseField name="converted_at" type="string | null">
      ISO 8601 timestamp of when the referral was converted (set when status is not `lead`)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether there are more results available
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.affonso.io/v1/referrals?limit=10&status=customer" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```

  ```bash cURL with External User Filter theme={null}
  curl -X GET "https://api.affonso.io/v1/referrals?external_user_id=user_42" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```

  ```bash cURL with Expand theme={null}
  curl -X GET "https://api.affonso.io/v1/referrals?limit=10&expand=affiliate" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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
  }
  ```

  ```json Response with Expand theme={null}
  {
    "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
  }
  ```
</ResponseExample>