Fanvue API documentation
Fanvue API documentation for BetterFans Link: what works on a linked Fanvue account, linking with Fanvue's own sign-in, live reads, writes and events.
Product page: Fanvue API
BetterFans Link reaches Fanvue accounts through Fanvue's own API, with the access each creator gives the BetterFans app on Fanvue. It is independent of Fanvue and works only with Fanvue accounts linked to your workspace. For those accounts it gives you the same routes, objects, keys, webhooks and MCP tools that OnlyFans and Fansly accounts use. Fanvue support is in Beta. This page covers what works on a Fanvue account, how its data differs and what it does not support.
What works on a Fanvue account
This table lists every route an API key can call and whether it works for a Fanvue account. A route marked No returns 400 not_supported_on_platform for a Fanvue account. Every response for one account names its platform in meta.platform.
| Route | Method and path | Fanvue | Notes |
|---|---|---|---|
| Who am I | GET /v1/me | Yes | |
| List accounts | GET /v1/accounts | Yes | Add platform=onlyfans, platform=fansly or platform=fanvue to list one platform. |
| Create link | POST /v1/links | Yes | Set platform, or leave it out and the creator picks. |
| Get link | GET /v1/links/{linkId} | Yes | |
| Get account | GET /v1/accounts/{accountId} | Yes | |
| List fans | GET /v1/accounts/{accountId}/fans | Yes | |
| Get fan | GET /v1/accounts/{accountId}/fans/{fanId} | Yes | fresh=true reads the fan live on OnlyFans and Fansly, and every Fanvue read is live. On Fansly, message and post purchases count in spend.other. |
| Fan lists | GET /v1/accounts/{accountId}/lists | Yes | |
| List chats | GET /v1/accounts/{accountId}/chats | Yes | |
| List messages | GET /v1/accounts/{accountId}/chats/{fanId}/messages | Yes | On Fansly, fresh=true works for a chat the account already has. |
| Search messages | GET /v1/accounts/{accountId}/messages/search | No, OnlyFans and Fansly only | |
| Show typing | POST /v1/accounts/{accountId}/chats/{fanId}/typing | Yes | |
| Revenue summary | GET /v1/accounts/{accountId}/revenue | Yes | |
| List transactions | GET /v1/accounts/{accountId}/transactions | Yes | On Fansly, message and post purchases have type other. |
| Mass messages | GET /v1/accounts/{accountId}/mass-messages | Yes | |
| Top content | GET /v1/accounts/{accountId}/posts | Yes | Tips per post are set on Fansly and null on OnlyFans. |
| Tracking links | GET /v1/accounts/{accountId}/links | Yes | url is null on Fansly, which does not say the address fans open. |
| Online fans | GET /v1/accounts/{accountId}/online-fans | Yes | On Fansly, since is null and fresh=true checks up to 500 fans. |
| Vault | GET /v1/accounts/{accountId}/vault | Yes | |
| Call OnlyFans | GET /v1/accounts/{accountId}/onlyfans/{path} | No, OnlyFans only | |
| Call Fansly | GET /v1/accounts/{accountId}/fansly/{path} | No, Fansly only | |
| Call Fanvue | GET /v1/accounts/{accountId}/fanvue/{path} | Yes | |
| Create action | POST /v1/accounts/{accountId}/actions | Yes | Fansly takes send_message and unsend_message. Fanvue takes every type. |
| Get action | GET /v1/actions/{actionId} | Yes | |
| List actions | GET /v1/actions | Yes |
An account id is the creator's Fanvue user id, and a fan id is the fan's Fanvue user id. Both are lowercase UUIDs, so keep every id as a string. A fan list id is the id of one of the creator's custom lists, also a UUID, or the id Fanvue gives one of its smart lists, such as subscribers.
API keys for Fanvue
You call these routes with a BetterFans Link key, the same one that reads your OnlyFans and Fansly accounts. Owners, admins and developers create keys on the API keys page of the dashboard. A bfl_test_ key reads the sandbox creators, and a bfl_live_ key reads the accounts linked to your workspace. See keys and scopes.
curl "https://betterfans.link/v1/accounts?platform=fanvue" \
-H "Authorization: Bearer $BFL_KEY"Link a Fanvue account
A creator links their own Fanvue account from a hosted link. Create it with Create link and platform set to fanvue, or leave platform out and let the creator pick Fanvue on the page. Then send its url to the creator. The link works for 24 hours.
curl -X POST "https://betterfans.link/v1/links" \
-H "Authorization: Bearer $BFL_KEY" \
-H "Content-Type: application/json" \
-d '{ "note": "Noa Lind", "platform": "fanvue" }'On the link page the creator presses Continue to Fanvue. A BetterFans page then names your workspace and asks them to press Continue to Fanvue once more, so use a workspace name the creator will recognize. Fanvue shows its own sign-in and asks the creator to allow BetterFans, then sends them back to the link, which says when they are connected. The creator types their Fanvue password on Fanvue only: BetterFans Link never sees it, and a two-factor code, if Fanvue asks for one, goes on Fanvue's page too.
- The creator signs in with their own Fanvue login. A team member login cannot connect an account yet, and the link fails with
not_creator_account. - A Fanvue account can be connected in one place at a time. If it is already connected somewhere else, the link fails with
account_in_use, and it has to be disconnected there before a new link can connect it. - If the creator declines on Fanvue, or does not allow everything BetterFans Link asks for, the link fails with
declinedormissing_scopes. See link failures. - When the account connects,
account.connectedfires. A Fanvue account ishealthyat once: there is no first sync to wait for. - A Fanvue account uses three statuses:
healthy,needs_relinkanddisconnected. It turnsneeds_relinkwhen Fanvue stops accepting the access the creator gave, for example because the creator removed BetterFans under Connected apps on Fanvue, andaccount.status_changedfires. Send the creator a new link. See account status. - Removing the account from your workspace ends your access to it.
To open the link inside your own app, see the Fanvue sign-in in the connect guide: Fanvue's sign-in does not run inside a frame, so a modal opens it in a popup window.
Every read is live
BetterFans Link keeps no copy of a Fanvue account. Every read asks Fanvue at that moment:
meta.sourceisliveandmeta.asOfis null on every response, and the account'slastSyncedAtis always null.- Each read counts as one live call toward the workspace's plan. A linked Fanvue account counts as one account, like any other.
fresh=truechanges nothing, since every read is live already. A read of a chat never marks it read on Fanvue.- When Fanvue errors or is slow, the read fails with
fanvue_errororfanvue_timeout. There is no synced copy to fall back on, so retry after a short wait. - When the account is not
healthy, every read of its data fails with409account_unavailable. Get account still answers, without asking Fanvue, with the status and every count at 0.
For a report over many fans or many days, read less often and keep what you need on your side.
Writes on a Fanvue account
A Fanvue account takes every action type, through Fanvue's own API. Create them with Create action and a key with the write scope, once writes are switched on for the account. Over MCP, the write tools create the same actions.
send_messagesends a fan a message with optional vault media. To make it paid, setpriceCentsto 300 or more, and attach media: a paid Fanvue message needs at least one media item.send_mass_messagegoes to fan lists, withaudience.listIdsandaudience.excludeListIds.audience.fanIdsreturns400invalid_parameteron a Fanvue account.unsend_messagetakes back one message, withfanId, or every copy of a mass message, with itsmassMessageIdand nofanId.add_fan_to_listandremove_fan_from_listchange the creator's custom lists. Fanvue's smart lists fill themselves, so they cannot be changed.- Show typing shows the fan that the account is typing.
| Write | Action type | Fanvue | Notes |
|---|---|---|---|
| Send message | send_message | Yes | On Fansly it is free, goes to a chat the account already has and attaches free vault media only. On Fanvue a paid message needs media. |
| Send mass message | send_mass_message | Yes | On Fanvue it goes to lists, never to single fans. |
| Unsend message | unsend_message | Yes | On OnlyFans and Fanvue it can take back every copy of a mass message. |
| Add fan to list | add_fan_to_list | Yes | |
| Remove fan from list | remove_fan_from_list | Yes |
AI clients that sign in with OAuth wait for your team to approve each write. See writes and approvals for how an action runs.
What a Fanvue account does not take
- Search messages returns
400not_supported_on_platform: Fanvue has no message search. Read the chat with List messages instead. The MCP toolsearch_messagesreturns the same error. - Call OnlyFans and Call Fansly return the same error for a Fanvue account.
- Fanvue accounts never send
fan.typing,fan.online,message.likedormessage.unliked.
Sending the same request again fails the same way, so check the account's platform with List accounts before you call.
Where Fanvue data differs
A Fanvue account answers with the same objects as the other platforms, filled from Fanvue's own answer. Where this table says a field is always 0 or always null, Fanvue does not give that value. Do not read it as a real zero. Webhook data follows the same rules.
| Resource | Field | OnlyFans | Fansly | Fanvue |
|---|---|---|---|---|
| Account | status | Any of the seven statuses. | Never awaiting_selfie or restricted. | healthy, needs_relink or disconnected. Never syncing, awaiting_2fa, awaiting_selfie or restricted: Fanvue signs in on its own page and BetterFans keeps no copy to sync. |
| Account | lastSyncedAt | When BetterFans last synced the account. Reads come from that copy unless fresh=true. | When the last sync pass finished. Reads come from that copy unless fresh=true. | Always null: BetterFans keeps no copy. Each read of the account's data asks Fanvue at that moment (meta.source live) and counts as a live call; listing accounts does not ask Fanvue. |
| Account detail | subscriptionPrice | The subscription price. | The cheapest tier's price. Fansly sells subscriptions in tiers. | The subscription price from Fanvue's account settings. null when the creator has set none, or when Fanvue could not give it. |
| Account detail | counts.chats, counts.vaultItems | Counted from the synced copy. | Counted from the synced copy. | Always 0: BetterFans does not count them on Fanvue, whose media list gives no total. While the account needs a relink or is disconnected, every count and revenue30d is 0 and Fanvue is not asked. |
| Fan | spend.messages, spend.posts | What the fan paid for messages and for posts. | Always 0. Fansly reports message and post purchases together, so they count in spend.other. | What the fan paid for messages and for posts, refunds left out, from Fanvue's own totals for the fan. |
| Fan | spend.net | What the creator kept from the fan's payments. | What the creator kept from the fan's payments. | An estimate: 80 percent of spend.total, the usual creator share. Fanvue does not say what the creator kept from one fan. |
| Fan | counts.messages | Messages in the chat, from the synced copy. | Messages in the chat, from the synced copy. | Always 0. Fanvue does not count a fan's messages. |
| Fan | notes | The creator's private note about the fan with fresh=true, else null. | Always null. | The creator's private note about the fan, on every read, without fresh=true. null when there is none, or when Fanvue could not give it. |
| Fan | subscription.expiresAt | Set whenever the fan has subscribed. | Can be null for an active or expired fan, when Fansly says only whether the fan subscribes. | When the current period ends. Get fan and sort=subscribed always say; other lists say only while the subscription renews, and null for an expired fan. null for a fan who only follows. |
| Fan | subscription.price | What the fan pays for the subscription. | The price of the fan's tier. | The subscription's list price, from Fanvue's subscriber record: on Get fan when Fanvue has one for the fan, and when fans are listed with sort=subscribed. null in other lists. |
| Fan | List fans sort, status and search | Any sort works with any status and with search. | Any sort works with any status and with search. | A search lists fans by their latest message: with no sort it uses sort=recent, and sort=spend or sort=subscribed with a search answers invalid_parameter. sort=subscribed needs status=active; other statuses answer invalid_parameter. sort=spend ranks lifetime spend, so with a status other than all a page can hold fewer fans than limit. |
| Fan | presence | online when OnlyFans showed the fan as online in the last 5 minutes. Online fans uses the same rule. | online when the fan's status is automatic and Fansly saw them in the last 30 minutes. A fan who chose any status but automatic reads offline, whatever their last-seen time. Online fans uses the same rule. | online when Fanvue shows the fan as online now, unknown when the account has no chat with the fan or Fanvue does not say. Online fans uses the same rule. |
| Fan list | type | custom, or system for the platform's built-in lists. | Always custom. | custom for the creator's own lists, system for Fanvue's smart lists. |
| Fan list | fanCount | Always set. | null when Fansly has not given a count. | null when Fanvue has not given a count. |
| Fan summary | username | The handle, or u followed by the fan id when OnlyFans gives none. | The handle, or the bare fan id when Fansly gives none. | The handle, or the bare fan id when Fanvue gives none. |
| Chat | lastActivityAt | When the last message was sent, else when the chat last changed. | When the last message was sent, or null until that message has synced. | When the last message was sent, or null for a chat with no message yet. |
| Chat | lastMessage.price, lastMessage.media, lastMessage.tip | Filled, as List messages fills them. | Filled, as List messages fills them. | Always null, empty and null. Fanvue's chat list names only the last message's text, sender and time; List messages has the rest. |
| Chat | unreadCount | The platform's count of unread messages. | The platform's count of unread messages. | Fanvue's count of unread messages. A chat the creator marked unread by hand counts 1. |
| Message | purchased | For a paid message, whether the fan bought it. | Always null. Fansly does not tell a creator which fans bought a message. | For a paid message, whether the fan bought it, from Fanvue's media list for the chat; null for a message with no price, and for the last message in a chat list. |
| Message | price, media | Filled whenever the message has them. | Filled whenever the message has them. | From the chat's media list, read beside the messages: up to 100 media items for each page of messages. On a page whose messages carry more media than that, its oldest messages show no media and no price. Ask for fewer messages a page to avoid it. |
| Message | tip | What the fan tipped with the message. | What the fan tipped with the message. | What the fan tipped, from Fanvue's tip earnings at the tip's time; null when they do not name it. On an account that gets many tips, a page holding tips at more than 6 different times can show the oldest of them as null. Ask for fewer messages a page to avoid it. |
| Message | massMessageId | Set when the copy came from a mass message. | Always null. | The mass message's id, which is also the message's own id: Fanvue gives a mass message one id in every chat it reached, so the same message id shows in each of those chats. |
| Message | liked | Whether the message was liked. | Whether the other side liked the message. | Always null. Fanvue's message list does not say. |
| Media | thumbnailUrl, durationSeconds | Filled on synced and fresh=true reads alike. | Always null with fresh=true. Synced reads fill them. | Fanvue's own signed addresses, which expire. null when Fanvue gives none. Media named in events, and media past the first 40 on a page of posts or mass messages, carry their id alone (type other). |
| Transaction | type | subscription, tip, message, post, stream, referral or other. | subscription, tip, stream, referral or other. Message and post purchases are other, as are refunds, reversals and prizes. type=message or type=post answers invalid_parameter. | subscription (renewals included), tip, message, post, referral (affiliate rewards included) or other: media and checkout link sales, giveaways, refunds, chargebacks and held back earnings are other. There is no stream: type=stream answers invalid_parameter. |
| Transaction | description | What OnlyFans says the payment was for, when it says. | Always null. | Always null. |
| Transaction | messageId, postId | Always null. | Always null. | The message or post the payment was for, when Fanvue names it. On a tip, the chat message Fanvue writes for the tip. |
| Transaction | fanId on List transactions | Lists one fan's transactions. | Lists one fan's transactions. | Answers invalid_parameter: Fanvue cannot list one fan's transactions. Get fan has the fan's spend. |
| Transaction | gross, net, fee | Never negative. Refunds and chargebacks are not listed. | Negative on a refund or a reversal. | Negative on a refund or a chargeback. Where Fanvue holds back or releases earnings, gross and fee are 0 and only net moves. |
| Revenue summary | byType | Every type, message and post included. | message and post are always 0. Message and post purchases count in other. | Every type but stream, from Fanvue's own totals. Every count, in byType and in the series, is 0: Fanvue gives totals, not how many payments made them. |
| Post | tips | Always null. OnlyFans does not say which post a tip was for. | Tips on the post, or null when it has none. | Tips on the post, or null when it has none. |
| Post | Sort and order | recent is newest first, likes is most liked first. | recent is newest first, likes is most liked first. | Pinned posts first, then newest first, as Fanvue orders them. sort=likes answers invalid_parameter: Fanvue cannot sort posts by likes. |
| Tracking link | url | The address fans open. | Always null. Fansly does not state it. | The address fans open. |
| Tracking link | kind | tracking, or trial when the link gives a free subscription. | Always tracking. | tracking, or trial for a free trial link. Fanvue lists only the free trial links that are still active. |
| Tracking link | clicks | Always set. | null when Fansly has not given a count. | Set on a tracking link. null on a free trial link: Fanvue counts its redemptions, which are its subscribers, not clicks. |
| Tracking link | revenue | What fans who joined through the link have spent since it was created. | Fansly's own total for the link. | Fanvue's own total for a tracking link. 0 on a free trial link: Fanvue reports no revenue for one. |
| Tracking link | Links listed | Every link BetterFans has synced. | Every link BetterFans has synced. | Up to 200 tracking links, and every active free trial link. Fanvue cannot rank links, so BetterFans reads them and ranks them itself. |
| Vault item | url | The archived copy, or null until it is archived. | The archived copy. Before that, Fansly's own signed address while it works (it expires after several days), else null. Download the file instead of storing the address. | Fanvue's own signed address while it works, else null. Download the file instead of storing the address. |
| Vault item | folders | Every vault list the item is in. | Every album the item is in. | The folder asked for when the vault is read by folder, else empty: Fanvue's media list does not say which folders an item is in. A folder's id is its name. |
| Vault item | type=gif | Lists GIFs. | Lists GIFs. | Answers invalid_parameter: Fanvue does not tell GIFs apart from photos. |
| Online fans | since | When the fan came online. | Always null. Fansly does not say. | Always null. Fanvue says who is online now, not since when. |
| Online fans | fresh=true | Checks up to 1,000 fans, most recently active first. | Checks up to 500 fans, most recently seen first. | Every read is live. Lists the fans Fanvue shows online now, most recently active chats first, up to 500 fans. |
| Money | Every amount | Exact cents. | Fansly counts tenths of a cent. Each amount is rounded to the nearest cent, so a total can differ from the sum of its items by a few cents. | Exact cents. |
| Money | Every total | Sales only. Refunds and chargebacks are left out. | Every transaction Fansly records. Refunds and reversals count as negative amounts, so a total can go down. | The revenue summary and revenue30d leave refunds and chargebacks out, as on OnlyFans. A fan's spend leaves out what was refunded. List transactions shows each reversal as its own negative row. |
| Mass message | sort=revenue | Ranks every mass message sent in the window. | Not on Fansly: Mass messages answers not_supported_on_platform. | Ranks every mass message sent in the window, up to 200. A window holding more answers invalid_parameter (param from), and so does one with more than 1,000 mass messages sent after it (param to): Fanvue cannot rank mass messages or list them by date, so BetterFans reads the window whole. |
Webhook events
Fanvue accounts send the shared events in the same shapes as the other platforms, among them message.received, message.sent, message.unsent, message.purchased, transaction.created, subscriber.new, and the account.* and link.failed events.
A Fanvue mass message sends no message.sent: Fanvue sends one notice for the whole mass message, not one for each fan, and it arrives as fanvue.message.mass_sent instead.
They also send the fanvue.* events: each of Fanvue's own creator.* notifications for the account, renamed, with data holding the account and fanvue, Fanvue's data object as Fanvue sent it. A fanvue.* event is recorded only while an enabled live endpoint of yours lists its type, so list only the ones you need. Fanvue documents the fields of each notification.
Direct access and the SDK
A live key with Direct access can also call Fanvue's own API for the accounts it reaches, on the creator API, as it does for Fansly:
| Route | What it does |
|---|---|
GET /v1/fanvue/accounts | Lists the Fanvue accounts the key reaches. |
/v1/fanvue/access/... | Calls Fanvue's API as the account named in the x-fanvue-account-id header. |
These calls run right away, with no approval, and each one is a live call.
Test mode with Marlo
Test mode has one Fanvue sandbox creator, Marlo, next to Ivy, Juniper and Wren on OnlyFans and Sloane on Fansly. With a bfl_test_ key, GET /v1/accounts?platform=fanvue lists Marlo, and you do not link anyone.
Every account route except Call OnlyFans, Call Fansly and Call Fanvue works against Marlo, with the same Fanvue rules as a linked account. Search messages returns not_supported_on_platform for Marlo, as it does for a linked Fanvue account. Responses have meta.source set to sandbox, and test reads never count as live calls.
A test action never calls Fanvue, and its result is only {"simulated": true}. See test mode.
Reads the routes do not cover
Call Fanvue runs a read-only Fanvue API GET for a linked Fanvue account. For example, GET /v1/accounts/{accountId}/fanvue/chats reads Fanvue's chats, and data holds Fanvue's JSON with emails, phone numbers and tokens removed.
- It always reads live, so
meta.sourceislive, and it counts as one live call. - Each endpoint takes only the query parameters its Fanvue reference lists. Any other returns
400invalid_parameter, witherror.paramnaming it. - Only
GETworks. To change anything on Fanvue, create an action. - It needs a live key. With a test key it returns
404resource_not_found. - Over MCP,
search_apianddescribe_endpointhelp find a path, andcall_apireads it.
Fanvue errors
These are the errors to plan for on a Fanvue account.
| Code | Status | When | What to do |
|---|---|---|---|
fanvue_error | 502 | Fanvue answered with an error. | Retry after a short wait. If it keeps failing, read the account with GET /v1/accounts/{accountId}, since its status may have changed. |
fanvue_timeout | 502 | Fanvue did not answer in time. | Retry later. |
account_unavailable | 409 | The account is not healthy. error.accountStatus holds the status. | Send the creator a new link. Do not retry in a loop. See account status. |
not_supported_on_platform | 400 | The route works on other platforms only, such as Search messages. | See what a Fanvue account does not take. |
rate_limited | 429 | Fanvue or your plan asked to slow down. | Wait for Retry-After, then retry. |
Fanvue is a trademark of its owner. BetterFans Link is not affiliated with, sponsored by, or endorsed by Fanvue.