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

# Fans and user lists

> Find subscribers, group fans into lists, and save notes

Find a creator’s subscribers and group them into lists for [mass messages](https://docs.ofauth.com/v3/guides/how-to/mass-message.md). Keep each fan’s OnlyFans user ID alongside the creator’s linked account ID.

## Before you start

Use `subscribers:read` for the subscriber search below. Complete [authorization](https://docs.ofauth.com/v3/guides/link.md) and select a [linked account](https://docs.ofauth.com/v3/api-reference/account/linked-accounts.md). Install the [TypeScript SDK](https://docs.ofauth.com/v3/sdk/typescript.md) version 4. Create a client on your server:

```typescript theme={null}
import { OFAuthClient } from "@ofauth/onlyfans-sdk"

const client = new OFAuthClient({
	accessToken: process.env.ACCESS_TOKEN!,
	linkedAccountId: process.env.LINKED_ACCOUNT_ID!
})
```

Scopes are the permissions your app requests when the user authorizes it. The [API reference](https://docs.ofauth.com/v3/api-reference.md) lists the permissions for each request.

## Use the right ID

The `x-linked-account-id` header selects the creator. A fan’s OnlyFans user ID goes in user, subscriber, and message routes. A list ID selects a saved group of fans. Save fan and list IDs with the creator’s linked account ID. Use a fan ID to select one recipient, or a list ID to select a group.

## Find subscribers

```typescript theme={null}
const subscribers = await client.access.subscribers.listActive({
	limit: 20,
	query: "alex"
})
```

Use `/v3/access/subscribers` for all subscribers, `/subscribers/active` for active subscribers, and `/subscribers/expired` for expired subscribers. Choose the route for the subscription status you need.

List responses use `{ items, page }`. Read the results from `items`. If `page.hasMore` is `true`, send `page.nextCursor` as the next request’s `cursor`. Keep the same filters.

### Subscriber filters

| Parameter | Meaning |
| - | - |
| `limit` | Number of items to return (1-20, default: 10) |
| `cursor` | Value from `page.nextCursor` in the previous response |
| `query` | Text to search for |
| `isOnline` | Values: `0`, `1`, `true`, `false`. Filter by online status |
| `minSpend` | Minimum total spend |
| `spentDateStart` | Start of total-spend date window |
| `spentDateEnd` | End of total-spend date window |
| `tipAmount` | Tip amount filter |
| `durationMonths` | Subscription duration in months |
| `isInactive` | Values: `0`, `1`, `true`, `false`. Filter by inactive subscription state |
| `hasRecommenders` | Values: `0`, `1`, `true`, `false`. Filter by recommender activity |

Use `minSpend` and spending dates to find fans for a campaign. `GET /v3/access/subscribers/count` has its own filters, including `type`, `hasAutoprolong`, and `newPriceLessThan`. Use count filters only on that route.

Read one user with `GET /v3/access/users/123456`. User IDs identify fans on OnlyFans. Linked account IDs identify the account shared with your authorization. Store both IDs together.

## Organize user lists

```typescript theme={null}
const list = await client.access.lists.create({
	body: { name: "Campaign audience" }
})
```

Save `list.id`. To find lists, use `GET /v3/access/lists`, which returns `items` and `page`. It accepts `limit`, `cursor`, `query`, `filter`, and `isChat`. See the [API reference](https://docs.ofauth.com/v3/api-reference.md) for filter values.

| Method | Route |
| - | - |
| `GET` | `/v3/access/lists/:listId` |
| `PATCH` | `/v3/access/lists/:listId` |
| `DELETE` | `/v3/access/lists/:listId` |
| `GET` | `/v3/access/lists/:listId/users` |
| `POST` | `/v3/access/lists/:listId/users/:userId` |
| `DELETE` | `/v3/access/lists/:listId/users/:userId` |
| `POST` | `/v3/access/users/:userId/lists` |

To add one fan, send `POST /v3/access/lists/101/users/123456`. To add the fan to multiple lists, send `POST /v3/access/users/123456/lists` with `{ "listIds": [101, 202] }`. You can send 1 to 5 list IDs. Use `DELETE /v3/access/lists/101/users/123456` to remove the fan from the list.

Send to these lists with [mass messages](https://docs.ofauth.com/v3/guides/how-to/mass-message.md). User lists hold fans. Media folders hold files in the [Vault](https://docs.ofauth.com/v3/guides/media.md).

## Record notes and subscriber preferences

| Operation | Request body |
| - | - |
| `PUT /v3/access/subscribers/123456/note` | `{ "notice": "Prefers studio sets" }` |
| `DELETE /v3/access/subscribers/123456/note` | No body |
| `PUT /v3/access/subscribers/123456/display-name` | `{ "displayName": "Alex" }` |
| `PUT /v3/access/subscribers/123456/discount` | `{ "discount": 20, "period": 3 }` |

Notes accept up to 1,000 characters. Display names accept 1 to 100 characters. Discounts accept whole numbers from 5 to 60 percent and periods from 1 to 12 months.

## Restrict or block a fan

| Method | Route |
| - | - |
| `POST` | `/v3/access/users/:userId/restrict` |
| `DELETE` | `/v3/access/users/:userId/restrict` |
| `GET` | `/v3/access/users/restrict` |
| `POST` | `/v3/access/users/:userId/block` |
| `DELETE` | `/v3/access/users/:userId/block` |
| `GET` | `/v3/access/users/blocked` |

Restricting and blocking a fan are separate actions. Check which actions the user response allows. Check the response to your request before updating your app. Restricted and blocked lists accept `limit`, `cursor`, and `query`.

To send welcome messages, read the active subscriber pages and save each fan’s ID. Then send an [individual message](https://docs.ofauth.com/v3/guides/how-to/send-message.md). Store the message ID to prevent repeat sends. Use [Realtime events](https://docs.ofauth.com/v3/guides/realtime-onlyfans-events.md) to receive updates when new activity occurs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.