Link a creator

Send a creator a hosted link, follow their sign-in, handle a failure, and relink an account that needs it.

A creator links their OnlyFans account to your workspace on a hosted page. They type their OnlyFans email and password there themselves, and answer any two-factor code or selfie check OnlyFans asks for. You never see the password. This guide creates the link, follows it to the end, and covers what to do when it fails.

Create the link

Call Create link with a note that names the creator. The note shows next to the link in the dashboard, so you can tell links apart later. Any key with the read scope can create links.

Create a link

curl -X POST "https://app.betterfans.link/v1/links" \
  -H "Authorization: Bearer $BFL_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Jess Rivers" }'

The response holds a HostedLink with an id and a url. Keep the id to follow progress. Send the url to the creator.

Creating a link needs no approval and changes nothing on OnlyFans. Nothing is linked until the creator finishes.

Over MCP, the link_account tool does the same and returns the url and linkId.

In the dashboard, owners, admins and developers use Link an account on the Accounts page, in live mode. A team member can sign in there with the creator's OnlyFans email and password and hand the creator only the step OnlyFans asks them for, such as a code sent to their phone or a selfie, or send the creator a link to do everything. Every link shows on the Linking page.

Send it to the creator

The link works for 24 hours and is for one creator. Something like this works well.

Here is the link to connect your OnlyFans account: <url>
Open it on a device where you can sign in to OnlyFans. You type your OnlyFans email and password on that page yourself, so we never see your password.
Keep your phone nearby. OnlyFans may ask for a two-factor code or a quick selfie check.
Keep the page open until it says you are connected. It takes a few minutes.

Follow progress

Two ways to know how it went.

Webhooks. account.connected fires when the account is linked, with the account in data.account and the link id in data.linkId. link.failed fires when the sign-in ends without linking, with the reason in data.failure.code.
Polling. Get link returns the link's status, and while the creator is signing in, a step in plain words. Over MCP, use get_link. Check every few seconds at most, and stop once status is no longer waiting or in_progress.

A link that nobody finishes in 24 hours ends as expired, and a link someone cancels in the dashboard ends as cancelled. Read those from Get link.

Link statuses

`status`	What it means	What to do
`waiting`	Nobody has opened the link yet.	Make sure the creator got it.
`in_progress`	The creator is signing in. `step` says where they are.	Nothing, unless `step` shows they are stuck.
`connected`	The account is linked. `accountId` holds its id.	Read the account. It shows `syncing` for up to 30 minutes.
`failed`	The sign-in did not work.	Find the reason, fix it, then create a new link.
`expired`	Nobody finished within 24 hours.	Create a new link and send it again.
`cancelled`	Someone cancelled the link in the dashboard.	Create a new link if it is still wanted.

Steps the creator sees

step is one of these while the link is waiting or in_progress, and null once it ends.

`step`	What it means	What the creator does
Waiting for the creator	The link has not been opened yet.	Open the link.
Signing in	OnlyFans is checking the email and password.	Wait.
Human check	OnlyFans asked for a human check.	Complete the check on the page.
Waiting for 2FA code	OnlyFans asked for a two-factor code.	Enter the code from their authenticator app, text message or email.
Waiting for selfie	OnlyFans asked for face verification.	Open the selfie link or scan the QR code on the page with their phone.
Verifying	The sign-in went through and is being checked.	Wait.
Syncing	The sign-in worked and the first sync is starting.	Wait until the page says they are connected.

When it connects

accountId on the link, and data.account.id on the webhook, hold the new account's id. It is the creator's OnlyFans user id, and it is the accountId in every account route.

Tell the user two things about a new account.

It shows syncing for up to 30 minutes while its history fills in. Totals are low until then. See account status.
API writes start switched off. An owner or admin turns them on in the account's settings before any action can run. See writes and approvals.

When it fails

A failed link has a reason in data.failure.code on the link.failed webhook, and on the Linking page in the dashboard. Fix the cause, then create a new link.

`failure.code`	What happened	What to do
`bad_credentials`	OnlyFans did not accept the email or password.	Ask the creator to check their email and password on onlyfans.com, then send a new link.
`account_restricted`	OnlyFans has limited the account.	The creator has to resolve the restriction with OnlyFans first. A new link will not help until then.
`otp_exhausted`	OnlyFans stopped the two-factor step after too many attempts.	Wait a while before trying again, then send a new link.
`face_failed`	The selfie check did not pass.	Send a new link. The creator should take the selfie in good light, with their face in the frame.
`timeout`	The sign-in did not finish in time.	Send a new link. The creator should keep the page open until it says they are connected.
`cancelled`	The sign-in was stopped before it finished.	Create a new link if the account should still be linked.
`unknown`	Something else went wrong.	Send a new link. If it happens again, contact hello@betterfans.link with the link id.

Handle a code not in this table as unknown.

Relink an account

An account in needs_relink, awaiting_2fa, awaiting_selfie or disconnected needs the creator to sign in again. Create a new link the same way and send it to the creator. When they finish, account.connected fires with data.relinked set to true, the account keeps its id and synced history, and its status goes back to healthy.

A restricted account cannot be fixed with a link. The creator has to resolve the restriction with OnlyFans first.

In test mode

A link made over the API with a test key is still a real link: the creator signs in to a real OnlyFans account. The dashboard links accounts in live mode only. Its account.connected and link.failed events go to your test mode webhook endpoints. To build against sample data without linking anyone, use the sandbox creators that come with test mode.

Link a creator

On this page