BetterFans Link: the OnlyFans APIBetterFans Link

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.

RouteMethod and pathOnlyFansNotes
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-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}Yes
Call FanslyGET /v1/accounts/{accountId}/fansly/{path}No, Fansly only
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 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.

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

Create an OnlyFans link
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.connected fires and the account shows syncing for 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.failed fires. Three failures happen on OnlyFans only: account_restricted when OnlyFans has limited the account, otp_exhausted after too many two-factor attempts, and face_failed when 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_changed fires. 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_message sends a fan a message. Add mediaIds to attach vault media, and priceCents to make it a paid message.
  • send_mass_message sends one message to fan lists or a set of fans. The action shows an estimate of how many fans it will reach.
  • unsend_message takes back a message. Pass a massMessageId and leave out fanId to take back every copy of a mass message.
  • add_fan_to_list and remove_fan_from_list change the creator's fan lists.
WriteAction typeOnlyFansNotes
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

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_selfie when OnlyFans asked for face verification. Send the creator a hosted link so they can finish the selfie check.
  • restricted when 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.source is live.
  • Each endpoint takes only the query parameters the OnlyFans site sends to it. Any other returns 400 invalid_parameter, with error.param naming it.
  • Only GET works. To change anything on OnlyFans, 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.

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.

CodeStatusWhenWhat to do
onlyfans_error502OnlyFans 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_timeout502OnlyFans 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 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.

On this page