# List referrals
URL: /docs/api-reference/referrals/list-referrals
Description: Returns a paginated list of referred customers.

**GET** `https://www.promotekit.com/api/v1/referrals`

Returns a paginated list of referrals (referred users) in your organization.

## Authentication

Requires a Bearer token in the `Authorization` header.

## Parameters

- `affiliate_id` (query): string (uuid) - Filter by affiliate UUID
- `email` (query): string (email) - Filter by referred customer email (exact match)
- `stripe_customer_id` (query): string - Filter by Stripe customer ID
- `subscription_status` (query): string - Filter by subscription status. Possible values: `signed_up`, `active`, `trialing`, `canceled`, `past_due`. Pass a comma-separated list to filter by multiple statuses (e.g. `?subscription_status=active,trialing`).
- `limit` (query): integer (default: 10) - Number of records to return (default: 10, max: 100)
- `page` (query): integer (default: 1) - Page number (1-indexed)

## Responses

### 200 - Successful response

- `success`: boolean **(required)**
- `data`: array **(required)**
- `pagination`: object **(required)**

### 401 - Authentication failed

- `success`: boolean **(required)**
- `error`: object **(required)**

### 429 - Rate limit exceeded

- `success`: boolean **(required)**
- `error`: object **(required)**