# Phone handoff

Let users on a computer finish connecting on their phone by scanning a QR code, where the platform's app already has them signed in.

Many people are not signed in to Instagram, TikTok or WhatsApp on their computer, but they are on their phone. A phone handoff turns the connect into a QR code: the user scans it, approves in the app they are already signed in to, and goes back to the computer, where your app sees the new account.

## Start a handoff

Add `handoff=true` to the connect call. Your brand parameters work as usual, because the phone always shows the [welcome screen](https://pozy.ai/docs/connect/welcome-screen) first.

```bash cURL
curl "https://api.pozy.ai/v1/connect/tiktok?profileId=6650c1f2a9e4b7d3c8a1f0e2&handoff=true&brandName=Acme" \
  -H "Authorization: Bearer $POZY_API_KEY"
```
```ts Node
const res = await fetch("https://api.pozy.ai/v1/connect/tiktok?profileId=6650c1f2a9e4b7d3c8a1f0e2&handoff=true&brandName=Acme", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
// data.handoff: { id, url, expiresAt }
```
```python Python
resp = requests.get(
    "https://api.pozy.ai/v1/connect/tiktok",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={"profileId": "6650c1f2a9e4b7d3c8a1f0e2", "handoff": "true", "brandName": "Acme"},
    timeout=30,
)
handoff = resp.json()["handoff"]
```

```json
{
  "authUrl": "https://pozy.ai/connect/welcome/3f9c2b1e-8d47-4a6b-9e21-5c0d7f3a8b64",
  "state": "...",
  "handoff": {
    "id": "3f9c2b1e-8d47-4a6b-9e21-5c0d7f3a8b64",
    "url": "https://pozy.ai/connect/m/3f9c2b1e-8d47-4a6b-9e21-5c0d7f3a8b64",
    "expiresAt": "2026-10-30T10:45:00.000Z"
  }
}
```

## Show the code

You have two options:

- **Draw your own QR code** of `handoff.url` with any QR library, inside your own UI.
- **Open `handoff.url` on the computer.** On a desktop browser it shows a ready-made page with the QR code that follows the status live, plus a link to continue on the computer instead.

`authUrl` is still valid. Offer it as a "Connect on this computer" link for users who are signed in on desktop.

The code works for 30 minutes.

## Wait for the result

Poll [`GET /v1/connect/handoffs/{handoffId}`](https://pozy.ai/docs/api/getConnectHandoff) every 2 to 5 seconds while the code is on screen, or listen for the `account.connected` webhook.

```bash
curl "https://api.pozy.ai/v1/connect/handoffs/3f9c2b1e-8d47-4a6b-9e21-5c0d7f3a8b64" \
  -H "Authorization: Bearer $POZY_API_KEY"
```

```json
{
  "id": "3f9c2b1e-8d47-4a6b-9e21-5c0d7f3a8b64",
  "status": "connected",
  "platform": "tiktok",
  "accounts": [
    { "id": "6651d3a7b2c9e4f1a0b8c7d6", "profileId": "6650c1f2a9e4b7d3c8a1f0e2", "username": "acmecoffee" }
  ],
  "error": null
}
```

| `status` | Meaning | What to show |
| --- | --- | --- |
| `waiting` | Nobody has scanned the code yet. | The QR code. |
| `opened` | The phone opened the link. | "Finish on your phone." |
| `connected` | Done. `accounts` lists what connected. | Success, and stop polling. |
| `failed` | The flow ended with an error. `error.code` uses the same values as the [redirect errors](https://pozy.ai/docs/connect/hosted-connect#errors-on-the-redirect). | The message and a retry button. |
| `expired` | 30 minutes passed. | A button that starts a new handoff. |

Stop polling at `connected`, `failed` or `expired`. A profile-scoped key can only read handoffs for its own profiles; anything else returns `404 handoff_not_found`.

## What the phone shows

1. Your welcome screen, then the platform's app or site, where the user is usually already signed in.
2. Any picker the platform needs (Pages, locations, numbers).
3. A closing screen that tells them to go back to the computer.

## Rules

- `handoff=true` cannot be combined with `welcome=false`, `headless=true` or `redirect_url`. The flow ends on the phone, so there is nowhere to redirect. These combinations return `400 invalid_field_value` with `param: handoff`.
- Use the handoff for platforms people mostly use on mobile: Instagram, TikTok, Snapchat, Threads and WhatsApp. For Google, Microsoft or LinkedIn a normal redirect is usually smoother.

## Endpoints

| Endpoint | What it does |
| --- | --- |
| [`GET /v1/connect/{platform}`](https://pozy.ai/docs/api/getConnectUrl) | Get OAuth connect URL |
| [`GET /v1/connect/handoffs/{handoffId}`](https://pozy.ai/docs/api/getConnectHandoff) | Get a phone handoff |