> ## 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 Affiliates

> Get a paginated list of all affiliates with optional filtering and expansion

## Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number for pagination. Must be a positive integer.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Number of results per page. Maximum value is 200. Default is 50.
</ParamField>

<ParamField query="partnership_status" type="string">
  Filter by partnership approval status. Valid values: `pending`, `approved`, `rejected`.
</ParamField>

<ParamField query="search" type="string">
  Search by name, email, or tracking ID. Case-insensitive partial matching. Maximum 100 characters.
</ParamField>

<ParamField query="group_id" type="string">
  Filter by affiliate group.
</ParamField>

<ParamField query="program_id" type="string">
  Filter by specific program (defaults to team's program).
</ParamField>

<ParamField query="sort" type="string">
  Sort field and direction in the format `field:direction`. Valid fields: `createdAt`, `updatedAt`, `name`, `partnershipStatus`. Valid directions: `asc`, `desc`. Example: `createdAt:desc`.
</ParamField>

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

<ParamField query="createdLte" type="string">
  Filter affiliates 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 in the response. Valid values: `promoCodes`, `commissionOverrides`, `invoiceDetails`, `payoutMethod`. You can combine multiple values: `promoCodes,payoutMethod`.
</ParamField>

## Response

The response includes a paginated list of affiliates and pagination metadata.

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

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

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

    <ResponseField name="name" type="string">
      The affiliate's display name
    </ResponseField>

    <ResponseField name="email" type="string">
      The affiliate's email address
    </ResponseField>

    <ResponseField name="tracking_id" type="string">
      Unique tracking ID for the affiliate
    </ResponseField>

    <ResponseField name="source" type="string">
      Source of the affiliate creation (e.g., `"api"`, `"dashboard"`)
    </ResponseField>

    <ResponseField name="partnership_status" type="string | null">
      Partnership status with the program: `"PENDING"`, `"APPROVED"`, `"REJECTED"`, or `null` if no partnership exists
    </ResponseField>

    <ResponseField name="onboarding_completed" type="boolean">
      Whether the affiliate has completed their onboarding process
    </ResponseField>

    <ResponseField name="program_id" type="string">
      The affiliate program ID the affiliate is assigned to
    </ResponseField>

    <ResponseField name="group_id" type="string | null">
      The affiliate group ID if assigned, otherwise `null`
    </ResponseField>

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

<ResponseField name="pagination" type="object">
  Pagination metadata object containing:

  * `page` (integer): Current page number
  * `limit` (integer): Number of results per page
  * `total` (integer): Total number of affiliates matching the filters
  * `totalPages` (integer): Total number of pages
  * `hasNextPage` (boolean): Whether there is a next page
  * `hasPrevPage` (boolean): Whether there is a previous page
</ResponseField>

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

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

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "cmj8pptm10002p3010z8mk9ak",
        "name": "John Doe",
        "email": "john@example.com",
        "tracking_id": "PARTNER123",
        "source": "api",
        "partnership_status": "APPROVED",
        "onboarding_completed": true,
        "program_id": "cm7xutqbb0001yfkcrnpextmp",
        "group_id": "efbf3f29-efb1-4837-8924-7322606858f3",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 50,
      "totalPages": 5,
      "hasNextPage": true,
      "hasPrevPage": false
    }
  }
  ```

  ```json Response with Expand theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "cmj8pptm10002p3010z8mk9ak",
        "name": "John Doe",
        "email": "john@example.com",
        "tracking_id": "PARTNER123",
        "source": "api",
        "partnership_status": "APPROVED",
        "onboarding_completed": true,
        "program_id": "cm7xutqbb0001yfkcrnpextmp",
        "group_id": "efbf3f29-efb1-4837-8924-7322606858f3",
        "created_at": "2024-01-15T10:30:00Z",
        "promoCodes": [
          {
            "code": "JOHN25",
            "promo_code_id": null,
            "coupon_id": "coupon_123",
            "discount_type": "percentage",
            "discount_value": 25,
            "duration": "forever",
            "created_at": "2024-01-15T10:30:00Z"
          }
        ],
        "commissionOverrides": [
          {
            "id": "override_123",
            "incentive_id": "incentive_456",
            "incentive_name": "Premium Commission",
            "incentive_type": "commission",
            "amount": 15,
            "is_percentage": true,
            "apply_to": "all_plans",
            "product_ids": [],
            "approval_type": "hold_period",
            "hold_period_days": 30,
            "incentive_length": "customer_lifetime",
            "length_value": null,
            "variable_commission": false,
            "variable_config": null
          }
        ],
        "invoiceDetails": {
          "company_name": "John LLC",
          "first_name": "John",
          "last_name": "Doe",
          "address_line_1": "123 Main St",
          "address_line_2": null,
          "city": "New York",
          "postal_code": "10001",
          "state": "NY",
          "country": "US",
          "vat_id": null,
          "tax_id": null,
          "vat_validated": false,
          "vat_validated_at": null
        },
        "payoutMethod": {
          "type": "paypal",
          "details": {
            "email": "john@example.com"
          }
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 50,
      "totalPages": 5,
      "hasNextPage": true,
      "hasPrevPage": false
    }
  }
  ```
</ResponseExample>