Phone handoff

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

curl "https://api.pozy.ai/v1/connect/tiktok?profileId=6650c1f2a9e4b7d3c8a1f0e2&handoff=true&brandName=Acme" \
  -H "Authorization: Bearer $POZY_API_KEY"

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 }

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"]

{
  "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} every 2 to 5 seconds while the code is on screen, or listen for the account.connected webhook.

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

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

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