> ## 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 & Subscribers

> List fans, track subscriptions, and manage user lists

## What You Can Build

* **Fan Dashboards**: View all subscribers, filter by status, track engagement
* **CRM Tools**: Organize fans into lists, add notes, track interactions
* **Subscription Analytics**: Monitor churn, renewal rates, lifetime value
* **Targeted Campaigns**: Segment fans for personalized messaging

***

## Quick Example

<Info>
  Subscriber list endpoints are paginated and currently return up to 20 results per page. Use `limit` values up to `20` and paginate with `offset`.
</Info>

Get a list of all active subscribers:

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch("https://api.ofauth.com/v2/access/subscribers?type=active", {
    headers: {
      apikey: "YOUR_API_KEY",
      "x-connection-id": "conn_abc123"
    }
  })

  const fans = await response.json()
  console.log(`You have ${fans.length} active subscribers`)
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.ofauth.com/v2/access/subscribers",
      params={"type": "active"},
      headers={
          "apikey": "YOUR_API_KEY",
          "x-connection-id": "conn_abc123"
      }
  )
  fans = response.json()
  print(f"You have {len(fans)} active subscribers")
  ```
</CodeGroup>

***

## Common Operations

### List All Fans

Get all subscribers regardless of status:

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/subscribers?" + new URLSearchParams({
  type: "all",
  limit: "20",
  offset: "0"
}), {
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123"
  }
})

const fans = await response.json()
// Returns array of fan objects with subscription details
```

### Filter by Subscription Status

```javascript theme={null}
// Active subscribers only
const active = await fetch(
  "https://api.ofauth.com/v2/access/subscribers?type=active",
  { headers }
)

// Expired (churned) subscribers
const expired = await fetch(
  "https://api.ofauth.com/v2/access/subscribers?type=expired",
  { headers }
)

// All-time subscribers
const all = await fetch(
  "https://api.ofauth.com/v2/access/subscribers?type=all",
  { headers }
)
```

### Search Subscribers

```javascript theme={null}
const response = await fetch(
  "https://api.ofauth.com/v2/access/subscribers?" + new URLSearchParams({
    query: "john",
    type: "active"
  }),
  { headers }
)
```

### Get Fan Details

Fetch detailed information about a specific user:

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/users/123456", {
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123"
  }
})

const fan = await response.json()
// Returns full user profile
```

***

## User Lists

Organize fans into custom lists for targeted messaging.

### Get All Lists

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/users/lists", {
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123"
  }
})

const lists = await response.json()
// Returns custom lists like "VIPs", "New Fans", etc.
```

### Get Users in a List

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/users/lists/LIST_ID/users?" + new URLSearchParams({
  limit: "20",
  offset: "0"
}), {
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123"
  }
})

const usersInList = await response.json()
```

### Create a List

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/users/lists", {
  method: "POST",
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "VIP Fans"
  })
})

const newList = await response.json()
```

### Add User to a List

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/users/lists/LIST_ID/users/USER_ID", {
  method: "POST",
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123"
  }
})
```

### Add User to Multiple Lists

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/users/USER_ID/lists", {
  method: "POST",
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    listIds: [123, 456, 789]
  })
})
```

### Remove User from a List

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/users/lists/LIST_ID/users/USER_ID", {
  method: "DELETE",
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123"
  }
})
```

***

## Subscriber Management

Manage individual subscriber relationships with notes, discounts, and custom names.

### Update Subscriber Note

Add or update a private note for a subscriber:

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/subscribers/123456/note", {
  method: "PUT",
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    notice: "VIP fan - always respond quickly!"
  })
})
```

### Apply Discount to Subscriber

Offer a subscription discount to a specific fan:

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/subscribers/123456/discount", {
  method: "PUT",
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    discount: 50,       // Discount percentage (e.g., 50 for 50% off)
    duration: 1         // Number of months
  })
})
```

### Set Custom Display Name

Set a custom name to help identify a subscriber:

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/subscribers/123456/custom-name", {
  method: "PUT",
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    displayName: "John (Friend from Twitter)"
  })
})
```

<Tip>
  Custom display names are private and only visible to you. They help organize fans when usernames aren't descriptive.
</Tip>

***

## User Management

### Restrict a User

Restrict a user from interacting:

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/users/123456/restrict", {
  method: "POST",
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123"
  }
})
```

### Unrestrict a User

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/users/123456/restrict", {
  method: "DELETE",
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123"
  }
})
```

### Get Restricted Users

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/users/restrict", {
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123"
  }
})
```

### Get Blocked Users

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/users/blocked", {
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123"
  }
})
```

***

## API Endpoints

### Subscribers

| Endpoint                                      | Method | Description             |
| --------------------------------------------- | ------ | ----------------------- |
| `/v2/access/subscribers`                      | GET    | List all subscribers    |
| `/v2/access/subscribers/{userId}/note`        | PUT    | Update subscriber note  |
| `/v2/access/subscribers/{userId}/discount`    | PUT    | Apply discount          |
| `/v2/access/subscribers/{userId}/custom-name` | PUT    | Set custom display name |

### Users

| Endpoint                             | Method | Description           |
| ------------------------------------ | ------ | --------------------- |
| `/v2/access/users/{userId}`          | GET    | Get user details      |
| `/v2/access/users/search`            | GET    | Search users          |
| `/v2/access/users/list`              | GET    | Get users by IDs      |
| `/v2/access/users/{userId}/restrict` | POST   | Restrict a user       |
| `/v2/access/users/{userId}/restrict` | DELETE | Unrestrict a user     |
| `/v2/access/users/restrict`          | GET    | List restricted users |
| `/v2/access/users/blocked`           | GET    | List blocked users    |

### User Lists

| Endpoint                                         | Method | Description                |
| ------------------------------------------------ | ------ | -------------------------- |
| `/v2/access/users/lists`                         | GET    | Get all user lists         |
| `/v2/access/users/lists`                         | POST   | Create a user list         |
| `/v2/access/users/lists/{listId}`                | GET    | Get a user list            |
| `/v2/access/users/lists/{listId}`                | PATCH  | Update a user list         |
| `/v2/access/users/lists/{listId}`                | DELETE | Delete a user list         |
| `/v2/access/users/lists/{listId}/users`          | GET    | Get users in a list        |
| `/v2/access/users/lists/{listId}/users/{userId}` | POST   | Add user to a list         |
| `/v2/access/users/lists/{listId}/users/{userId}` | DELETE | Remove user from list      |
| `/v2/access/users/{userId}/lists`                | POST   | Add user to multiple lists |

<Card title="Full API Reference" icon="book" href="/api-reference/access/overview">
  See complete endpoint documentation
</Card>

***

## Query Parameters

### Subscribers Query

| Parameter | Type   | Default  | Description                        |
| --------- | ------ | -------- | ---------------------------------- |
| `limit`   | number | 10       | Results per page (1-20)            |
| `offset`  | number | 0        | Pagination offset                  |
| `type`    | string | "active" | Filter: `all`, `active`, `expired` |
| `query`   | string | ""       | Search by name/username            |

### Advanced Filters

The `filter` object supports additional filtering:

| Filter        | Type   | Description                     |
| ------------- | ------ | ------------------------------- |
| `promoId`     | string | Filter by promotion ID          |
| `trial_id`    | string | Filter by trial ID              |
| `duration`    | string | Filter by subscription duration |
| `tips`        | string | Filter by tip amount            |
| `total_spent` | string | Filter by total spent           |
| `online`      | string | Filter by online status         |

***

## Subscriber Data Structure

Each subscriber object includes:

```json theme={null}
{
  "id": 123456,
  "username": "fanname",
  "name": "Fan Display Name",
  "avatar": "https://media.ofauth.com/...",
  "subscribedAt": "2024-01-15T10:30:00Z",
  "expiredAt": "2024-02-15T10:30:00Z",
  "renewedAt": null,
  "subscribeDuration": 30,
  "totalSpent": 49.99,
  "subscribesCount": 3,
  "hasStories": false,
  "isVerified": false
}
```

***

## Tips & Best Practices

<Tip>
  **Pagination**: Large fan lists are paginated. Use the `offset` and `limit` parameters to page through results. Maximum limit is 20 per request.
</Tip>

<Info>
  **Caching**: Fan lists don't change frequently. Consider caching subscriber data and refreshing periodically rather than on every request.
</Info>

<Warning>
  **Privacy**: Handle fan data responsibly. Don't expose personal information and follow applicable data protection regulations.
</Warning>

***

## Related Guides

<CardGroup cols={2}>
  <Card title="Messaging & Chats" icon="messages" href="/guides/messaging">
    Send targeted messages to fan segments
  </Card>

  <Card title="Earnings & Analytics" icon="chart-line" href="/guides/earnings">
    Track revenue by fan
  </Card>
</CardGroup>