# Link a creator

Connect a creator's OnlyFans account to the workspace, or reconnect one that needs a relink, with a hosted link the creator opens themselves.

## Calls

| Step | MCP tool | REST route |
| --- | --- | --- |
| Create the link | `link_account` | `POST /v1/links` |
| Follow progress | `get_link` | `GET /v1/links/{linkId}` |
| Confirm the account | `account_health` | `GET /v1/accounts/{accountId}` |

Creating a link needs no approval and changes nothing on OnlyFans. Owners, admins and developers can create links.

## Steps

1. Call `link_account` with a `note` naming the creator, such as "Jess Rivers". It returns a `url` and a `linkId`.
2. Give the user the `url` to send to the creator, with the message below. The link works for 24 hours and is for that creator only.
3. Check progress with `get_link` when the user asks. `status` moves from `waiting` to `in_progress` and ends as `connected`, `failed`, `expired` or `cancelled`. While the link is `waiting` or `in_progress`, `step` says where the creator is in plain words. Once it ends, `step` is null.
4. When `status` is `connected`, `accountId` holds the account. Call `account_health` with it. A new account shows `syncing` for up to 30 minutes while its history fills in.
5. Tell the user two things about a new account. Totals are low until syncing ends. API writes start switched off, and an owner or admin switches them on in the account's settings.

## What to tell the creator

Something like this, in the user's voice.

```text
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. The link works for 24 hours.
```

## Steps the creator sees

`step` shows one of these while the link is `waiting` or `in_progress`.

| 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. |

## 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. |

The reason for a failure arrives in the `link.failed` webhook as `data.failure.code` and on the Linking page in the dashboard.

| `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 any code not in this table as `unknown`.

## Relinking

An account in `needs_relink`, `awaiting_2fa`, `awaiting_selfie` or `disconnected` goes through the same steps with a new link. The synced history stays in place, and the account goes back to `healthy` when the creator finishes. A `restricted` account cannot be fixed with a link. Only OnlyFans can lift the restriction.