# Link a creator

Connect a creator's OnlyFans or Fansly 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 or Fansly. Owners, admins and developers can create links.

## Steps

1. Call `link_account` with a `note` naming the creator, such as "Jess Rivers". Pass `platform` (`onlyfans` or `fansly`) when you know where the creator is. Leave it out and the creator picks the platform on the page. 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. Its `platform` says whether it is on OnlyFans or Fansly. 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, for OnlyFans.

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

And for Fansly.

```text
Here is the link to connect your Fansly account: <url>
You type your Fansly username or email and your password on that page yourself.
Fansly may send a code to your email or ask for one from your authenticator app. Have them nearby.
Keep the page open until it says you are connected. 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 | The platform is checking the sign-in details. | Wait. |
| Human check | OnlyFans asked for a human check. Fansly never asks for one. | Complete the check on the page. |
| Waiting for 2FA code | The platform asked for a two-factor code. | Enter the code from their authenticator app, text message or email. Fansly sends it by email or uses an authenticator app. |
| Waiting for selfie | OnlyFans asked for face verification. Fansly never asks for one. | 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` | The platform did not accept the sign-in details: the email and password on OnlyFans, the username or email and password on Fansly. | Ask the creator to check their sign-in details on the platform, then try again on the same link while it is valid, or send a new link. |
| `code_expired` | The two-factor code expired before the sign-in finished. | The creator enters their details again on the same link to get a new code, or you send a new link. |
| `account_in_use` | The account is already connected somewhere else. A Fansly account can be connected in one place at a time. | Remove the account from the other workspace first, then send a new link. |
| `platform_unavailable` | The platform could not finish the sign-in right now. | Wait a few minutes, then try again on the same link while it is valid, or 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 relink keeps the account's platform. A `restricted` account cannot be fixed with a link. Only OnlyFans can lift the restriction. Fansly accounts are never `restricted` or `awaiting_selfie`.