Build a platform

If you build a product on Pozy, such as a scheduler, an agency tool or a CRM with social features, your customers' accounts all live in your one workspace. Profiles keep them apart. This page is the blueprint: one profile per customer, your own id on it, and events that come back already labelled with that id.

#The model

Requests carry the profileId in. Webhooks carry profiles[].externalId out, so routing an event needs no lookup.

A customer with three Facebook Pages and two Instagram accounts connects all five into their single profile. Do not create one profile per account.

#Step 1: create a profile when a customer signs up

Use your own customer id as the externalId and keep the returned _id on your customer record.

curl -X POST https://api.pozy.ai/v1/profiles \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp", "externalId": "cus_8f3a2" }'

const res = await fetch("https://api.pozy.ai/v1/profiles", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Acme Corp", externalId: "cus_8f3a2" }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
await db.customers.update("cus_8f3a2", { pozyProfileId: data.profile._id });

import os, requests

resp = requests.post(
    "https://api.pozy.ai/v1/profiles",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={"name": "Acme Corp", "externalId": "cus_8f3a2"},
)
profile_id = resp.json()["profile"]["_id"]

externalId is unique in your workspace. If a signup is retried, the second create returns 409 with code: "profile_external_id_conflict" and the existing id in details.existingProfileId, so you never end up with two profiles for one customer. Lost the id? GET /v1/profiles?externalId=cus_8f3a2 finds it (profiles).

#Step 2: let the customer connect their accounts

Ask for a connect URL with the customer's profileId and your own redirect_url, then send the customer's browser there.

curl "https://api.pozy.ai/v1/connect/instagram?profileId=6720f3b1c9e4a85d2f0b7c14&redirect_url=https://app.example.com/integrations/done" \
  -H "Authorization: Bearer $POZY_API_KEY"

const query = new URLSearchParams({ profileId, redirect_url: "https://app.example.com/integrations/done" });
const connectRes = await fetch(`https://api.pozy.ai/v1/connect/instagram?${query}`, {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await connectRes.json();
if (!connectRes.ok) throw new Error(data.error);
res.redirect(data.authUrl);

resp = requests.get(
    "https://api.pozy.ai/v1/connect/instagram",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={"profileId": profile_id, "redirect_url": "https://app.example.com/integrations/done"},
)
auth_url = resp.json()["authUrl"]  # redirect the customer here

The customer signs in on the platform, picks the Page or channel if the platform asks, and lands back on your redirect_url. Every screen in between is hosted by Pozy. You can put your own brand on them with the welcome screen, or draw the selection steps in your own UI with headless connect.

On your server, listen for account.connected. It names the customer through externalId:

{
  "id": "evt_2c7e1a9f04b8d3e5",
  "event": "account.connected",
  "timestamp": "2026-10-30T14:02:11.000Z",
  "profiles": [{ "id": "6720f3b1c9e4a85d2f0b7c14", "externalId": "cus_8f3a2" }],
  "account": {
    "accountId": "6720f41a8d3be96c1e5a02f7",
    "profileId": "6720f3b1c9e4a85d2f0b7c14",
    "platform": "instagram",
    "username": "acmecorp"
  }
}

account.disconnected arrives the same way when access ends, so you can show the customer a "Reconnect" button.

#Step 3: act on their behalf

Every call that works on accounts, posts, conversations or analytics accepts the customer's profileId or their accountIds. To post to everything a customer connected:

curl -X POST https://api.pozy.ai/v1/posts \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cus_8f3a2-post-1042" \
  -d '{
    "content": "Spring menu is live.",
    "mediaItems": [{ "type": "image", "url": "https://pozy.ai/media/spring-menu.jpg" }],
    "platforms": [
      { "platform": "instagram", "accountId": "6720f41a8d3be96c1e5a02f7" },
      { "platform": "facebook", "accountId": "6720f52b9a1cd47e3f8b06a2" }
    ],
    "scheduledFor": "2026-11-04T11:30:00",
    "timezone": "America/Chicago"
  }'

const listedRes = await fetch(`https://api.pozy.ai/v1/accounts?${new URLSearchParams({ profileId })}`, {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const listed = await listedRes.json();
if (!listedRes.ok) throw new Error(listed.error);
const res = await fetch("https://api.pozy.ai/v1/posts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Idempotency-Key": `cus_8f3a2-post-${draft.id}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    content: draft.text,
    mediaItems: draft.media,
    platforms: listed.accounts.map((a) => ({ platform: a.platform, accountId: a._id })),
    scheduledFor: draft.when,
    timezone: "America/Chicago",
  }),
});
if (!res.ok) throw new Error((await res.json()).error);

accounts = requests.get(
    "https://api.pozy.ai/v1/accounts",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={"profileId": profile_id},
).json()["accounts"]
requests.post(
    "https://api.pozy.ai/v1/posts",
    headers={
        "Authorization": f"Bearer {os.environ['POZY_API_KEY']}",
        "Idempotency-Key": f"cus_8f3a2-post-{draft_id}",
    },
    json={
        "content": "Spring menu is live.",
        "platforms": [{"platform": a["platform"], "accountId": a["_id"]} for a in accounts],
        "scheduledFor": "2026-11-04T11:30:00",
        "timezone": "America/Chicago",
    },
)

Derive idempotency keys from your own ids (cus_8f3a2-post-1042) so a retried job can never publish twice (idempotency).

#Step 4: route webhooks back to the customer

Register one endpoint for all customers and route on profiles[0].externalId, or give large customers their own endpoint filtered with profileIds. Route webhooks to tenants has a complete router.

#Keys: one master key or one per customer

A single full-access key on your backend is enough for most platforms. Add per-customer keys when part of your system should only ever see one customer, such as a worker that runs customer-written code, a reporting export, or an AI agent acting for one tenant. Scoped keys are for access control only: the rate limit belongs to the workspace and is shared by every key.

#What it costs

Profiles are free, including empty ones. You pay per connected account per month, counted across the whole workspace on the graduated ladder in Pricing: the more accounts your customers connect in total, the lower the rate for the extra ones.

To see what each customer costs you, ask for usage grouped by profile:

curl "https://api.pozy.ai/v1/usage?range=cycle&groupBy=profile" \
  -H "Authorization: Bearer $POZY_API_KEY"

attribution.groups has one entry per profile. Their sum plus attribution.unattributed (workspace-wide items such as the free credit and 10DLC fees) equals the totals (usage).

#Offboard a customer

1. Disconnect each of their accounts with DELETE /v1/accounts/{accountId}. An account stops counting toward your bill from the next UTC day.
2. Delete the profile with DELETE /v1/profiles/{profileId}. A profile that still has active connected accounts cannot be deleted, so step 1 comes first.
3. Delete or revoke any key you scoped to that profile.

A disconnected account can be reconnected into the same profile within one hour and keep its accountId. After that it is removed, scheduled posts that only targeted it are cancelled, and a later connection gets a new id.

#Checklist

• Create the profile with externalId at signup, store profile._id.
• Connect with the customer's profileId and your redirect_url.
• Handle account.connected and account.disconnected.
• Send Idempotency-Key on every create, derived from your own ids.
• Route webhooks on externalId.
• Watch per-customer cost with GET /v1/usage?groupBy=profile.