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.
| Route | Method and path | Fansly | 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 | Yes | |
| 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 | No, OnlyFans and Fanvue only | |
| 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} | Yes | |
| Call Fanvue | GET /v1/accounts/{accountId}/fanvue/{path} | No, Fanvue only | |
| 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 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.
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.
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.connectedfires and the account showssyncinguntil 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_relinkanddisconnected. It is neverawaiting_selfieorrestricted. See account status. - If Fansly signs the creator out, the account turns
needs_relinkandaccount.status_changedfires. 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_messagesends a fan a free message in the chat the account already has with that fan. It attaches free vault media only. Leave outpriceCents, since a price above 0 returns400invalid_parameter.unsend_messagetakes 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.
| Write | Action type | Fansly | 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 | No, OnlyFans and Fanvue only | 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 | No, OnlyFans and Fanvue only | |
| Remove fan from list | remove_fan_from_list | No, 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
400not_supported_on_platformfor a Fansly account. - The
send_mass_message,add_fan_to_listandremove_fan_from_listaction types return the same error when you create one for a Fansly account, witherror.paramset totype. No action is created. - A paid message is a
send_messagewithpriceCentsabove 0. On a Fansly account that returns400invalid_parameterinstead.
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.
| 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. |
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=trueit lists the fans the synced copy saw online in the last 30 minutes. Fansly does not say when a fan came online, sosinceis alwaysnull.
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.sourceislive. - Each endpoint takes only the query parameters the Fansly site sends to it. Any other returns
400invalid_parameter, witherror.paramnaming it. - Only
GETworks. To change anything on Fansly, 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.
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.
| Code | Status | When | What to do |
|---|---|---|---|
fansly_error | 502 | Fansly 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_timeout | 502 | Fansly did not answer in time. | Retry later, or read without fresh=true to get synced data. |
account_unavailable | 409 | The 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_platform | 400 | The 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.
OnlyFans accounts
What works on a linked OnlyFans account: routes, writes, linking with 2FA and selfie checks, statuses, live reads, events and errors.
Fanvue accounts
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.