Hosted connect pages

Hosted connect is the quickest way to get a user's account into Pozy. You make one API call, send the user's browser to the URL it returns, and Pozy handles the platform's consent screen, any Page or location picker, and the redirect back to your app.

The hosted pages run on pozy.ai. Add a welcome screen and they carry your name and logo instead of Pozy's.

#Start a connect

GET /v1/connect/{platform} returns an authUrl. profileId is required: it is the profile the new account joins.

curl "https://api.pozy.ai/v1/connect/instagram?profileId=6650c1f2a9e4b7d3c8a1f0e2&redirect_url=https://app.example.com/connected" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/connect/instagram?profileId=6650c1f2a9e4b7d3c8a1f0e2&redirect_url=https:%2F%2Fapp.example.com%2Fconnected", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);

// In an Express handler: res.redirect(data.authUrl)

import os
import requests

resp = requests.get(
    "https://api.pozy.ai/v1/connect/instagram",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={
        "profileId": "6650c1f2a9e4b7d3c8a1f0e2",
        "redirect_url": "https://app.example.com/connected",
    },
    timeout=30,
)
resp.raise_for_status()
auth_url = resp.json()["authUrl"]

{
  "authUrl": "https://www.instagram.com/oauth/authorize?client_id=...",
  "state": "c2Vzc2lvbi0..."
}

Send the browser to authUrl. Keep state if you want to match the callback to the request, but treat it as opaque. The link and the flow behind it expire after 30 minutes.

Call this endpoint from your server. The key in the Authorization header must never reach the browser.

#Platforms

{platform} is one of facebook, instagram, linkedin, twitter (X), tiktok, youtube, threads, pinterest, googlebusiness, snapchat, reddit, slack, whatsapp, google and microsoft.

A few platforms have their own start endpoint because they need extra input or behave differently:

#Parameters

The full list, with types and limits, is on Get OAuth connect URL.

#What the user sees

1. Welcome screen (optional): "Acme wants to connect to your Instagram", with your logo. It forwards to the platform after about a second.
2. The platform's consent screen: sign in, review the permissions, approve.
3. Picker (some platforms): choose the Facebook Pages, LinkedIn page, Pinterest board, business locations, WhatsApp number or Slack channels to connect. Several can be ticked where the platform allows it, and each becomes its own account.
4. Back to your app: the browser goes to redirect_url. With no redirect_url, the user sees a "You're connected" screen they can close.

Connects started from the Pozy dashboard return to Connections in the dashboard instead.

#Read the result

On success, Pozy adds these parameters to your redirect_url:

When a picker connects several accounts at once, the redirect names the first one. List the profile's accounts, or wait for one account.connected event per account, to get them all.

app.get("/connected", async (req, res) => {
  const { connected, accountId, profileId, error, error_message } = req.query;
  if (error) {
    return res.redirect(`/settings/channels?failed=${encodeURIComponent(String(error_message ?? error))}`);
  }
  await db.channels.upsert({ accountId, profileId, platform: connected });
  res.redirect("/settings/channels?connected=1");
});

#Errors on the redirect

A cancelled or failed connect sends the browser to redirect_url with error and platform, plus error_message you can show the user when one is available.

https://app.example.com/connected?error=oauth_denied&platform=instagram&is_user_fixable=true&stage=authorize&request_id=req_...

is_user_fixable=true means connecting again usually fixes it. Treat any error you do not recognise as a generic failure: new values can appear.

Errors that happen before the user leaves your app come back as a normal API error instead:

#Reconnect an account

Tokens expire and users revoke access. To repair an account, start a connect for the same platform with reconnectAccountId:

curl "https://api.pozy.ai/v1/connect/instagram?profileId=6650c1f2a9e4b7d3c8a1f0e2&reconnectAccountId=6651d3a7b2c9e4f1a0b8c7d6&redirect_url=https://app.example.com/connected" \
  -H "Authorization: Bearer $POZY_API_KEY"

The account keeps its id, its posts and its analytics history. Account health tells you which accounts need it.

#White-label notes

If your customers connect their own accounts through your product:

• Create one profile per customer and pass that profileId. Accounts never mix between customers.
• Turn on the welcome screen with your brand, so the first thing they see is your name.
• Your own platform apps, coming soon, will put your app's name on the platform's consent screen too.
• Route account.connected to the right customer with the event's profiles[].externalId. See Route webhooks to tenants.

#Endpoints