BetterFans Link: the OnlyFans APIBetterFans Link

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.

RouteMethod and pathFanvueNotes
Who am IGET /v1/meYes
List accountsGET /v1/accountsYesAdd platform=onlyfans, platform=fansly or platform=fanvue to list one platform.
Create linkPOST /v1/linksYesSet platform, or leave it out and the creator picks.
Get linkGET /v1/links/{linkId}Yes
Get accountGET /v1/accounts/{accountId}Yes
List fansGET /v1/accounts/{accountId}/fansYes
Get fanGET /v1/accounts/{accountId}/fans/{fanId}Yesfresh=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 listsGET /v1/accounts/{accountId}/listsYes
List chatsGET /v1/accounts/{accountId}/chatsYes
List messagesGET /v1/accounts/{accountId}/chats/{fanId}/messagesYesOn Fansly, fresh=true works for a chat the account already has.
Search messagesGET /v1/accounts/{accountId}/messages/searchNo, OnlyFans and Fansly only
Show typingPOST /v1/accounts/{accountId}/chats/{fanId}/typingYes
Revenue summaryGET /v1/accounts/{accountId}/revenueYes
List transactionsGET /v1/accounts/{accountId}/transactionsYesOn Fansly, message and post purchases have type other.
Mass messagesGET /v1/accounts/{accountId}/mass-messagesYes
Top contentGET /v1/accounts/{accountId}/postsYesTips per post are set on Fansly and null on OnlyFans.
Tracking linksGET /v1/accounts/{accountId}/linksYesurl is null on Fansly, which does not say the address fans open.
Online fansGET /v1/accounts/{accountId}/online-fansYesOn Fansly, since is null and fresh=true checks up to 500 fans.
VaultGET /v1/accounts/{accountId}/vaultYes
Call OnlyFansGET /v1/accounts/{accountId}/onlyfans/{path}No, OnlyFans only
Call FanslyGET /v1/accounts/{accountId}/fansly/{path}No, Fansly only
Call FanvueGET /v1/accounts/{accountId}/fanvue/{path}Yes
Create actionPOST /v1/accounts/{accountId}/actionsYesFansly takes send_message and unsend_message. Fanvue takes every type.
Get actionGET /v1/actions/{actionId}Yes
List actionsGET /v1/actionsYes

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.

List the Fanvue accounts your key can use
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.

Create a Fanvue link
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 declined or missing_scopes. See link failures.
  • When the account connects, account.connected fires. A Fanvue account is healthy at once: there is no first sync to wait for.
  • A Fanvue account uses three statuses: healthy, needs_relink and disconnected. It turns needs_relink when Fanvue stops accepting the access the creator gave, for example because the creator removed BetterFans under Connected apps on Fanvue, and account.status_changed fires. 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.source is live and meta.asOf is null on every response, and the account's lastSyncedAt is 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=true changes 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_error or fanvue_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 with 409 account_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_message sends a fan a message with optional vault media. To make it paid, set priceCents to 300 or more, and attach media: a paid Fanvue message needs at least one media item.
  • send_mass_message goes to fan lists, with audience.listIds and audience.excludeListIds. audience.fanIds returns 400 invalid_parameter on a Fanvue account.
  • unsend_message takes back one message, with fanId, or every copy of a mass message, with its massMessageId and no fanId.
  • add_fan_to_list and remove_fan_from_list change 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.
WriteAction typeFanvueNotes
Send messagesend_messageYesOn 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 messagesend_mass_messageYesOn Fanvue it goes to lists, never to single fans.
Unsend messageunsend_messageYesOn OnlyFans and Fanvue it can take back every copy of a mass message.
Add fan to listadd_fan_to_listYes
Remove fan from listremove_fan_from_listYes

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

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.

ResourceFieldOnlyFansFanslyFanvue
AccountstatusAny 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.
AccountlastSyncedAtWhen 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 detailsubscriptionPriceThe 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 detailcounts.chats, counts.vaultItemsCounted 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.
Fanspend.messages, spend.postsWhat 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.
Fanspend.netWhat 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.
Fancounts.messagesMessages 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.
FannotesThe 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.
Fansubscription.expiresAtSet 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.
Fansubscription.priceWhat 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.
FanList fans sort, status and searchAny 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.
Fanpresenceonline 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 listtypecustom, 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 listfanCountAlways set.null when Fansly has not given a count.null when Fanvue has not given a count.
Fan summaryusernameThe 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.
ChatlastActivityAtWhen 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.
ChatlastMessage.price, lastMessage.media, lastMessage.tipFilled, 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.
ChatunreadCountThe 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.
MessagepurchasedFor 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.
Messageprice, mediaFilled 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.
MessagetipWhat 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.
MessagemassMessageIdSet 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.
MessagelikedWhether the message was liked.Whether the other side liked the message.Always null. Fanvue's message list does not say.
MediathumbnailUrl, durationSecondsFilled 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).
Transactiontypesubscription, 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.
TransactiondescriptionWhat OnlyFans says the payment was for, when it says.Always null.Always null.
TransactionmessageId, postIdAlways 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.
TransactionfanId on List transactionsLists 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.
Transactiongross, net, feeNever 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 summarybyTypeEvery 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.
PosttipsAlways 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.
PostSort and orderrecent 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 linkurlThe address fans open.Always null. Fansly does not state it.The address fans open.
Tracking linkkindtracking, 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 linkclicksAlways 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 linkrevenueWhat 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 linkLinks listedEvery 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 itemurlThe 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 itemfoldersEvery 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 itemtype=gifLists GIFs.Lists GIFs.Answers invalid_parameter: Fanvue does not tell GIFs apart from photos.
Online fanssinceWhen the fan came online.Always null. Fansly does not say.Always null. Fanvue says who is online now, not since when.
Online fansfresh=trueChecks 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.
MoneyEvery amountExact 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.
MoneyEvery totalSales 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 messagesort=revenueRanks 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:

RouteWhat it does
GET /v1/fanvue/accountsLists 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.source is live, and it counts as one live call.
  • Each endpoint takes only the query parameters its Fanvue reference lists. Any other returns 400 invalid_parameter, with error.param naming it.
  • Only GET works. To change anything on Fanvue, create an action.
  • It needs a live key. With a test key it returns 404 resource_not_found.
  • Over MCP, search_api and describe_endpoint help find a path, and call_api reads it.

Fanvue errors

These are the errors to plan for on a Fanvue account.

CodeStatusWhenWhat to do
fanvue_error502Fanvue 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_timeout502Fanvue did not answer in time.Retry later.
account_unavailable409The 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_platform400The route works on other platforms only, such as Search messages.See what a Fanvue account does not take.
rate_limited429Fanvue 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.

On this page