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

# Fans

> List and retrieve fans with the Fanhaven API.

Fans are the CRM records for an artist. These endpoints are read-only and artist-wide.

Required scope: `fans:read`.

## List fans

```
GET /v1/fans
```

| Query          | Description                                   |
| -------------- | --------------------------------------------- |
| `page`         | Page number. Default `1`.                     |
| `per_page`     | Page size. Default `25`, max `100`.           |
| `search`       | Match first name, last name, email, or phone. |
| `email`        | Email match.                                  |
| `phone_number` | Phone match.                                  |

```bash theme={null}
curl "https://api.fanhaven.com/v1/fans?search=jane" \
  -H "Authorization: Bearer fh_live_..."
```

## Retrieve a fan

```
GET /v1/fans/:id
```

```bash theme={null}
curl "https://api.fanhaven.com/v1/fans/fan_..." \
  -H "Authorization: Bearer fh_live_..."
```

## Fan object

```json theme={null}
{
  "id": "fan_...",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "phone_number": "+15551234567",
  "sms_consent_at": null,
  "email_consent_at": null,
  "created_at": "2026-08-26T12:00:00.000Z"
}
```