BetterFans Link: the OnlyFans APIBetterFans Link

Fansly API documentation

Fansly API documentation for BetterFans Link: which routes and writes work on a linked Fansly account, API keys, linking, test mode and errors.

Product page: Fansly API

Fansly publishes no public developer API, API keys or documentation. BetterFans Link is independent of Fansly and works only with Fansly accounts linked to your workspace. For those accounts it gives you documented routes, API keys, webhooks and an MCP server. The routes, objects and events are the same ones OnlyFans accounts use. This page covers what works on a Fansly account and where its data differs from OnlyFans.

What works on a Fansly account

This table lists every route an API key can call and whether it works for a Fansly account. A route marked No returns 400 not_supported_on_platform for a Fansly account. Every response for one account names its platform in meta.platform.

RouteMethod and pathFanslyNotes
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/searchYes
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-messagesNo, OnlyFans and Fanvue only
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}Yes
Call FanvueGET /v1/accounts/{accountId}/fanvue/{path}No, Fanvue only
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 Fansly user id, and a fan id is the fan's Fansly user id. Fansly ids are too large for a JavaScript number to hold exactly, so keep every id as a string.

API keys for Fansly

Since Fansly issues no API keys, you call these routes with a BetterFans Link key. 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. One key works for OnlyFans, Fansly and Fanvue accounts alike. See keys and scopes.

List the Fansly accounts your key can use
curl "https://betterfans.link/v1/accounts?platform=fansly" \
  -H "Authorization: Bearer $BFL_KEY"

Link a Fansly account

Creators can link their own Fansly accounts on a page BetterFans Link hosts. Create the link with Create link and platform set to fansly, then send its url to the creator. The link works for 24 hours.

Create a Fansly link
curl -X POST "https://betterfans.link/v1/links" \
  -H "Authorization: Bearer $BFL_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Rae Vale", "platform": "fansly" }'

On that page the creator signs in with their Fansly username or email and password. If Fansly asks for a code, they type the one Fansly sent by email or the one from their authenticator app. Fansly has no selfie or human check.

  • A Fansly account can be connected in one place at a time. If it is already connected to another workspace, the link fails with account_in_use. Remove it there first, then send a new link.
  • When the account connects, account.connected fires and the account shows syncing until its first full sync finishes. Reads work during that time, but totals can be low.
  • A Fansly account uses five statuses: healthy, syncing, awaiting_2fa, needs_relink and disconnected. It is never awaiting_selfie or restricted. See account status.
  • If Fansly signs the creator out, the account turns needs_relink and account.status_changed fires. Send the creator a new link.
  • Removing the account from your workspace stops its sync and keeps the synced history. BetterFans Link does not sign the creator out at Fansly.

Link a creator covers following a link, failures and relinking.

Writes on a Fansly account

A Fansly account takes two action types, send_message and unsend_message. Create them with Create action and a key with the write scope, once writes are switched on for the account. Over MCP, the send_message and unsend_message tools create the same actions.

  • send_message sends a fan a free message in the chat the account already has with that fan. It attaches free vault media only. Leave out priceCents, since a price above 0 returns 400 invalid_parameter.
  • unsend_message takes back a message the account sent.

If the account has no chat with the fan yet, or a media item is not free, nothing is sent and the action ends failed with the reason in error.

WriteAction typeFanslyNotes
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_messageNo, OnlyFans and Fanvue onlyOn 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_listNo, OnlyFans and Fanvue only
Remove fan from listremove_fan_from_listNo, OnlyFans and Fanvue only

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 Fansly account does not take

Mass messages, paid messages and fan list changes work on OnlyFans and Fanvue, not on Fansly. The two tables above mark each route and action type.

  • The Mass messages and Call OnlyFans and Call Fanvue routes return 400 not_supported_on_platform for a Fansly account.
  • The send_mass_message, add_fan_to_list and remove_fan_from_list action types return the same error when you create one for a Fansly account, with error.param set to type. No action is created.
  • A paid message is a send_message with priceCents above 0. On a Fansly account that returns 400 invalid_parameter instead.

Sending the same request again fails the same way, so check the account's platform with List accounts before you call.

Where Fansly data differs

A Fansly account answers with the same objects as an OnlyFans account, but Fansly does not report everything OnlyFans does. Where this table says a field is always 0 or always null, Fansly does not give that value. Do not read it as a real zero, and do not tell anyone a fan spent nothing on messages because spend.messages is 0. 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.

How fresh Fansly data is

Reads come from the synced copy by default. New messages, sales, subscribers and post changes usually reach it within a minute, and a full sync about every 30 minutes catches anything missed. meta.asOf on each response, and the account's lastSyncedAt, say when the last full sync finished. Newer messages and sales can already be in the response.

Three routes read live from Fansly with fresh=true:

  • List messages, for a chat the account already has with that fan.
  • Get fan, which returns the fan's profile.
  • Online fans, which checks up to 500 of the account's fans, most recently seen first. Without fresh=true it lists the fans the synced copy saw online in the last 30 minutes. Fansly does not say when a fan came online, so since is always null.

Every other Fansly read comes from synced data, except Call Fansly, which always reads live. A live read is slower and calls Fansly with the creator's session, so use it for the one answer that must be current. See synced and live reads.

Fansly accounts send every shared webhook event except four: fan.online, message.liked, message.unliked and message.purchased. That includes message.received, message.unsent, fan.typing, transaction.created and subscriber.new. Event data has the same shapes as the API, so a Fansly transaction.created for a paid message has type set to other, as the table above says. See platforms in the event reference.

Test mode with Sloane

Test mode has one Fansly sandbox creator, Sloane, next to Ivy, Juniper and Wren on OnlyFans and Marlo on Fanvue. Every workspace sees the same five, and you do not link them. With a bfl_test_ key, GET /v1/accounts?platform=fansly lists Sloane.

Every account route except Call OnlyFans, Call Fansly and Call Fanvue works against Sloane, with the same Fansly rules as a linked account. Mass messages and the action types a Fansly account does not take return not_supported_on_platform for her, as they do for a linked Fansly account. Responses have meta.source set to sandbox.

A test action never calls Fansly, and its result is only {"simulated": true}. See test mode.

Reads the routes do not cover

Call Fansly runs a read-only Fansly API GET for a linked Fansly account, with the account's session. For example, GET /v1/accounts/{accountId}/fansly/account/me reads Fansly's account/me, and data holds the response part of Fansly's answer.

  • It always reads live, so meta.source is live.
  • Each endpoint takes only the query parameters the Fansly site sends to it. Any other returns 400 invalid_parameter, with error.param naming it.
  • Only GET works. To change anything on Fansly, 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.

Fansly errors

These are the errors to plan for on a Fansly account. The first three come from live reads, which can fail where a synced read would not.

CodeStatusWhenWhat to do
fansly_error502Fansly answered a live read 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.
fansly_timeout502Fansly did not answer in time.Retry later, or read without fresh=true to get synced data.
account_unavailable409The account's status stops live calls. error.accountStatus holds the status.Read without fresh=true for the synced copy. Do not retry in a loop. See account status.
not_supported_on_platform400The route or action type does not work on a Fansly account.See what a Fansly account does not take.

OnlyFans is a registered trademark of Fenix International Limited. Fansly and Fanvue are trademarks of their owners. BetterFans Link is not affiliated with, sponsored by, or endorsed by any of them.

On this page