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
Get a list of all active subscribers:
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`)
Common Operations
List All Fans
Get all subscribers regardless of status:
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
// 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
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:
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
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
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
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
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
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
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:
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:
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:
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)"
})
})
Custom display names are private and only visible to you. They help organize fans when usernames aren’t descriptive.
User Management
Restrict a User
Restrict a user from interacting:
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
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
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
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 |
Full API Reference
See complete endpoint documentation
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:
{
"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
Pagination: Large fan lists are paginated. Use the offset and limit parameters to page through results. Maximum limit is 20 per request.
Caching: Fan lists don’t change frequently. Consider caching subscriber data and refreshing periodically rather than on every request.
Privacy: Handle fan data responsibly. Don’t expose personal information and follow applicable data protection regulations.
