OnlyFans accounts
What works on a linked OnlyFans account: routes, writes, linking with 2FA and selfie checks, statuses, live reads, events and errors.
Product page: OnlyFans agency API
OnlyFans publishes no public developer API, API keys or documentation. BetterFans Link is independent of OnlyFans and works only with OnlyFans accounts linked to your workspace. OnlyFans accounts take every shared route, every action type and every shared webhook event, so most of the docs apply to them as written. This page collects what is specific to an OnlyFans account: linking, statuses, live reads, events and errors.
What works on an OnlyFans account
This table lists every route an API key can call and whether it works for an OnlyFans account. A route marked No returns 400 not_supported_on_platform for an OnlyFans account. Every response for one account names its platform in meta.platform.
| Route | Method and path | OnlyFans | 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 | 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} | Yes | |
| Call Fansly | GET /v1/accounts/{accountId}/fansly/{path} | No, Fansly only | |
| 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 OnlyFans user id, and a fan id is the fan's OnlyFans user id. They look like numbers, but keep every id as a string. See entities and ids.
API keys for OnlyFans
OnlyFans issues no API keys, so 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=onlyfans" \
-H "Authorization: Bearer $BFL_KEY"Link an OnlyFans account
Creators link their own OnlyFans accounts on a page BetterFans Link hosts. Create the link with Create link and platform set to onlyfans, 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": "Jess Rivers", "platform": "onlyfans" }'On that page the creator signs in with their OnlyFans email and password. OnlyFans may ask for a two-factor code from an authenticator app, a text message or email, a human check, or a selfie check. The creator answers each one on the same page.
- When the account connects,
account.connectedfires and the account showssyncingfor up to 30 minutes while its history fills in. Reads work during that time, but totals can be low. - If the sign-in ends without linking,
link.failedfires. Three failures happen on OnlyFans only:account_restrictedwhen OnlyFans has limited the account,otp_exhaustedafter too many two-factor attempts, andface_failedwhen the selfie check did not pass. See when it fails. - If OnlyFans signs the creator out or asks for a code or a selfie later, the account's status changes and
account.status_changedfires. Send the creator a new link.
Link a creator covers the message to send the creator, following a link and relinking.
Writes on an OnlyFans account
An OnlyFans account takes every action type. Create one with Create action and a key with the write scope, once writes are switched on for the account. Over MCP, the tool with the same name creates the same action.
send_messagesends a fan a message. AddmediaIdsto attach vault media, andpriceCentsto make it a paid message.send_mass_messagesends one message to fan lists or a set of fans. The action shows an estimate of how many fans it will reach.unsend_messagetakes back a message. Pass amassMessageIdand leave outfanIdto take back every copy of a mass message.add_fan_to_listandremove_fan_from_listchange the creator's fan lists.
| Write | Action type | OnlyFans | 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 |
A write needs a working session, so wait for the account to be healthy before you ask for one. AI clients that sign in with OAuth wait for your team to approve each write. See writes and approvals for how an action runs.
OnlyFans account statuses
An OnlyFans account can be in any of the seven statuses. Two of them happen on OnlyFans only.
awaiting_selfiewhen OnlyFans asked for face verification. Send the creator a hosted link so they can finish the selfie check.restrictedwhen OnlyFans limited the account. Only the creator can resolve that with OnlyFans, and a new link will not help until they do.
Five statuses stop every live call and every write: needs_relink, awaiting_2fa, awaiting_selfie, restricted and disconnected. Reads without fresh=true keep working from the synced copy. See account status.
How fresh OnlyFans data is
Reads come from the synced copy by default, so they are fast and do not use the creator's session on OnlyFans. meta.asOf on each response, and the account's lastSyncedAt, say how old the data is.
Three routes read live from OnlyFans with fresh=true: List messages, Get fan and Online fans. A live read is slower and calls OnlyFans with the creator's session, so use it for the one answer that must be current.
On OnlyFans, opening a chat marks it read. A live read of an OnlyFans chat's messages keeps the chat's unread state as it was. In the rare case that it cannot, meta.sideEffects holds thread_marked_read, and you should tell the creator the chat may look read in OnlyFans. See synced and live reads.
Webhook events from OnlyFans
OnlyFans accounts send every webhook event except the Fanvue events. Three events come from OnlyFans accounts only: fan.online, message.liked and message.unliked. OnlyFans accounts also send message.purchased when a fan buys a paid message, and fan.typing. See platforms in the event reference.
Test mode with Ivy, Juniper and Wren
Test mode has three OnlyFans sandbox creators, Ivy, Juniper and Wren. Every workspace sees the same ones, and you do not link them. With a bfl_test_ key, GET /v1/accounts?platform=onlyfans lists them.
Every account route except Call OnlyFans works against them, with the same OnlyFans rules as a linked account. Responses have meta.source set to sandbox. A test action never calls OnlyFans, and its result is only {"simulated": true}. See test mode.
Reads the routes do not cover
Call OnlyFans runs a read-only OnlyFans API GET for a linked OnlyFans account, with the account's session. For example, GET /v1/accounts/{accountId}/onlyfans/users/me reads OnlyFans' users/me, and data holds the JSON OnlyFans returned, with tokens, passwords, emails and phone numbers removed.
- It always reads live, so
meta.sourceislive. - Each endpoint takes only the query parameters the OnlyFans site sends to it. Any other returns
400invalid_parameter, witherror.paramnaming it. - Only
GETworks. To change anything on OnlyFans, 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.
OnlyFans errors
These are the errors to plan for on an OnlyFans account. The first three come from live reads, which can fail where a synced read would not.
| Code | Status | When | What to do |
|---|---|---|---|
onlyfans_error | 502 | OnlyFans 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. |
onlyfans_timeout | 502 | OnlyFans 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 works on another platform only, such as Call Fansly. | Check the account's platform with List accounts before you call. |
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.
BetterFans Link
OnlyFans API documentation for agencies and developers: REST routes, webhooks and an MCP server for OnlyFans, Fansly and Fanvue, with a test mode.
Fansly accounts
Fansly API documentation for BetterFans Link: which routes and writes work on a linked Fansly account, API keys, linking, test mode and errors.