Fanvue API Documentation

curl https://api.fanvue.com/chats \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "Authorization: Bearer <token>"

{
  "data": [
    {
      "createdAt": "2024-01-15T00:00:00.000Z",
      "lastMessageAt": "2024-01-15T00:00:00.000Z",
      "isRead": false,
      "isMuted": false,
      "unreadMessagesCount": 3,
      "user": {
        "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "handle": "sarah-jones",
        "displayName": "Sarah Jones",
        "nickname": "SarahK",
        "isTopSpender": true,
        "avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
        "registeredAt": "2024-01-10T12:00:00.000Z"
      },
      "lastMessage": {
        "text": "Hey there! How are you doing?",
        "type": "SINGLE_RECIPIENT",
        "uuid": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
        "sentAt": "2024-01-15T00:00:00.000Z",
        "hasMedia": true,
        "mediaType": "image",
        "senderUuid": "c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8",
        "sentByUserId": null
      }
    },
    {
      "createdAt": "2024-01-14T00:00:00.000Z",
      "lastMessageAt": null,
      "isRead": true,
      "isMuted": true,
      "unreadMessagesCount": 0,
      "user": {
        "uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "handle": "mike-smith",
        "displayName": "Mike Smithly",
        "nickname": null,
        "isTopSpender": false,
        "avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
        "registeredAt": "2024-01-10T12:00:00.000Z"
      },
      "lastMessage": null
    },
    {
      "createdAt": "2024-01-15T00:00:00.000Z",
      "lastMessageAt": "2024-01-15T00:00:00.000Z",
      "isRead": true,
      "isMuted": false,
      "unreadMessagesCount": 0,
      "user": {
        "uuid": "3bbe6394-2830-4646-a8ba-4a0a05426947",
        "handle": "johnny-doey",
        "displayName": "Johnny Doey",
        "nickname": "JohnnyD",
        "isTopSpender": true,
        "avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
        "registeredAt": "2024-01-10T12:00:00.000Z"
      },
      "lastMessage": {
        "text": "Check out my new post!",
        "type": "BROADCAST",
        "uuid": "c3d4e5f6-7890-1234-5678-9abcdef01234",
        "sentAt": "2024-01-15T00:00:00.000Z",
        "hasMedia": true,
        "mediaType": "image",
        "senderUuid": "c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8",
        "sentByUserId": null
      }
    }
  ],
  "pagination": {
    "page": 1,
    "size": 2,
    "hasMore": false
  }
}

Returns a paginated list of chat conversations with optional filtering, searching, and sorting.

Available Filters (via filter parameter):

unread - Only unread chats
online - Only online users
subscribed_to - Users you’re subscribed to
not_muted - Exclude muted chats
subscribers - Only subscribers (creator-only)
followers - Only followers (creator-only)
recent_subscribers - Recently subscribed (creator-only)
not_answered - Unanswered chats (creator-only)
spent_more_than_50 - High spenders (creator-only)
on_free_trial - Free trial users (creator-only)
has_tipped - Users who have tipped (creator-only)
spenders - All spenders (creator-only)
exclude_creators - Exclude creator accounts (creator-only)

Sort Options (via sortBy parameter):

most_recent_messages (default) - Sort by most recent message
online_now - Prioritize online users
most_unanswered_chats - Sort by unanswered count

Scope required: read:chat

Some filters are only available to creators. Using creator-only filters as a non-creator will return a 403 error.

Returns a paginated list of chat conversations with optional filtering, searching, and sorting. **Available Filters** (via `filter` parameter): - `unread` - Only unread chats - `online` - Only online users - `subscribed_to` - Users you're subscribed to - `not_muted` - Exclude muted chats - `subscribers` - Only subscribers (creator-only) - `followers` - Only followers (creator-only) - `recent_subscribers` - Recently subscribed (creator-only) - `not_answered` - Unanswered chats (creator-only) - `spent_more_than_50` - High spenders (creator-only) - `on_free_trial` - Free trial users (creator-only) - `has_tipped` - Users who have tipped (creator-only) - `spenders` - All spenders (creator-only) - `exclude_creators` - Exclude creator accounts (creator-only) **Sort Options** (via `sortBy` parameter): - `most_recent_messages` (default) - Sort by most recent message - `online_now` - Prioritize online users - `most_unanswered_chats` - Sort by unanswered count <Info>Scope required: `read:chat`</Info> <Warning>Some filters are only available to creators. Using creator-only filters as a non-creator will return a 403 error.</Warning>

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Query parameters

pagedoubleOptional>=1Defaults to 1

Page number to retrieve (starts from 1)

sizedoubleOptional1-50Defaults to 15

Number of items to return per page (1-50, default: 15)

customListIdstringOptionalformat: "uuid"

Filter chats by custom list UUID

smartListIdslist of enumsOptional

Filter chats by smart list type(s)

filterlist of enumsOptional

Filter types to apply (can specify multiple via repeated params)

searchstringOptional<=100 characters

Search term to filter chats by user name/handle

sortByenumOptional

Sort order for chat list (default: most_recent_messages)

Allowed values:

Response

List of chats

datalist of objects

Array of chat conversations

paginationobject

Pagination information

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

410

Gone Error

429

Too Many Requests Error

Get list of chats

Authentication

Headers

Query parameters

Response

Errors