# Build a platform

Give each of your customers a profile, connect their accounts into it, post on their behalf and route webhooks back to the right customer.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Card, Cards } from 'fumadocs-ui/components/card';

By the end of this page, each of your customers has a profile, their accounts are connected inside it, and every webhook lands on the right customer record.

## One profile per customer

Give each profile your own customer id as its `externalId`, and every webhook carries that id back, so routing an event needs no lookup on your side.

One profile per customer is the whole model. A customer with 3 Facebook Pages and 2 Instagram accounts connects all 5 into their one profile.

Profiles are free. Each connected account is metered ([pricing](/pricing)).

<Cards>
  <Card title="Publishing" href="/multi-tenant/publishing" description="Retry-safe posting for every customer: idempotency keys, media, per-profile queues" />
  <Card title="Analytics dashboards" href="/multi-tenant/analytics" description="Serve each customer their own metrics from a sync worker" />
  <Card title="Inbox and DMs" href="/multi-tenant/inbox" description="One inbox per customer, written by webhooks" />
</Cards>

Requests carry `profileId` in, and events carry your own `externalId` back on `profiles[]`:

<Mermaid
  chart={`flowchart LR
  subgraph app ["Your app"]
    DB[("Your database
customer cus_8f3a2
+ its profileId")]
  end
  subgraph zernio ["Zernio"]
    PROF["Profile, externalId cus_8f3a2"]
    IG["Instagram @acme"]
    TT["TikTok @acme"]
    X["X @acme"]
  end
  DB -->|"your API calls carry profileId"| PROF
  PROF --> IG
  PROF --> TT
  PROF --> X
  IG -.->|"webhooks carry externalId cus_8f3a2"| DB
  linkStyle 4 stroke:#6b7280,color:#6b7280,stroke-dasharray:6 4;`}
/>

Every new team starts with a profile named "Default". Keep it for your own accounts and create one profile per customer next to it.

## Before you start

You need an API key.

## Step 1: Create a profile per customer

When a customer signs up, call `POST /v1/profiles` with a `name` for your dashboard and your own customer id as `externalId`.

Store `profile._id` on the customer record for the API calls in the next steps. If you lose it, `GET /v1/profiles?externalId=cus_8f3a2` returns the profile.

`externalId` is unique among the profiles you own, so a retried signup cannot create a second profile for the same customer (see [If it fails](#if-it-fails)).

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: created } = await zernio.profiles.createProfile({
  body: {
    name: 'Acme Corp',
    externalId: 'cus_8f3a2',
  },
});

const profileId = created.profile._id; // store on your customer record
```
</Tab>
<Tab value="Python">
```python
from zernio import Zernio

client = Zernio()

created = client.profiles.create_profile(
    name="Acme Corp",
    external_id="cus_8f3a2",
)

profile_id = created["profile"]["_id"]  # store on your customer record
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/profiles" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp", "externalId": "cus_8f3a2" }'
```
</Tab>
</Tabs>

Response (`201`):

```json
{
  "message": "Profile created successfully",
  "profile": {
    "_id": "66a1f0c2a4b9d3e8f1a2b3c4",
    "name": "Acme Corp",
    "externalId": "cus_8f3a2",
    "isDefault": false,
    "createdAt": "2026-09-08T10:00:00Z"
  }
}
```

The [Create profile endpoint](/profiles/create-profile) lists every field.

## Step 2: Connect their accounts

Call `GET /v1/connect/{platform}` with the customer's `profileId`, so the account lands in their profile.

Pass `headless=true` to draw the selection screens yourself, instead of using the ones Zernio hosts.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data: connect } = await zernio.connect.getConnectUrl({
  path: { platform: 'instagram' },
  query: { profileId, redirect_url: 'https://your-app.com/callback' },
});
// Send the customer's browser to connect.authUrl
```
</Tab>
<Tab value="Python">
```python
connect = client.connect.get_connect_url(
    platform="instagram",
    profile_id=profile_id,
    redirect_url="https://your-app.com/callback",
)
# Send the customer's browser to connect["authUrl"]
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/connect/instagram?profileId=66a1f0c2a4b9d3e8f1a2b3c4&redirect_url=https://your-app.com/callback" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```
</Tab>
</Tabs>

Response (`200`):

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

The [connecting accounts guide](/guides/connecting-accounts) covers headless mode and the platforms that add a selection step (Facebook Pages, LinkedIn organizations, Pinterest boards).

A customer who manages several Pages runs this flow once per Page, always with the same `profileId`.

Subscribe to [`account.connected`](/webhooks) to learn about new connections on your server. `profiles[0].externalId` names the customer and `account.accountId` is the new account:

```json
{
  "event": "account.connected",
  "profiles": [{ "id": "66a1f0c2a4b9d3e8f1a2b3c4", "externalId": "cus_8f3a2" }],
  "account": {
    "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
    "profileId": "66a1f0c2a4b9d3e8f1a2b3c4",
    "platform": "instagram",
    "username": "acmecorp"
  }
}
```

`account.disconnected` carries the same identifiers when a token dies or a customer removes access.

The onboarding flow end to end:

<Mermaid
  chart={`%%{init: {"themeVariables": {"signalColor": "#ec3013"}}}%%
sequenceDiagram
  participant C as Customer
  participant A as Your app
  participant Z as Zernio
  participant P as Instagram
  A->>Z: POST /v1/profiles
  Z-->>A: profile._id, stored on your customer record
  C->>A: clicks "Connect Instagram"
  A->>Z: GET /v1/connect/instagram?profileId=...
  Z-->>A: authUrl
  A->>C: redirect to authUrl
  C->>P: signs in and authorizes
  P->>C: redirect to your redirect_url
  Z-->>A: webhook account.connected (accountId + externalId)
  Note over A: the customer is profiles[0].externalId`}
/>

### White-label the connect window [#white-label]

Pass `welcome=true` and `authUrl` opens a Zernio-hosted screen with your brand: "Acme wants to connect to your Instagram". After about a second it continues to the platform's authorization screen with no click.

Save your brand once for the workspace with `PUT /v1/connect/welcome-screen`, so every connect call uses it:

```bash
curl -X PUT "https://zernio.com/api/v1/connect/welcome-screen" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "showByDefault": true, "brandName": "Acme", "logoUrl": "https://acme.com/logo.png", "theme": { "primaryColor": "#1D4ED8", "cornerRadius": 12 } }'
```

- **Per call:** `brandName`, `logoUrl`, `primaryColor` and `welcomeTheme` on `GET /v1/connect/{platform}` override the saved settings for that call. `welcomeTheme` changes copy, colors, font, icons and Terms and Privacy links ([all keys](/connect/get-connect-url)).
- **Whole flow:** the brand also appears on the account and channel pickers. With no `redirect_url`, the flow ends on a branded page saying whether the account connected.
- **Limits:** the link lasts 30 minutes, it can't be combined with `headless=true` or `signup=hosted`, and the platform's own authorization screen still names the Zernio app.

## Step 3: Post on their behalf

Call `GET /v1/accounts` with the customer's `profileId`, then `POST /v1/posts` with those account ids.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data: listed } = await zernio.accounts.listAccounts({
  query: { profileId },
});

const { data: published } = await zernio.posts.createPost({
  body: {
    content: 'Posted from your app.',
    platforms: listed.accounts.map((a) => ({
      platform: a.platform,
      accountId: a._id,
    })),
    publishNow: true,
  },
});

console.log(published.post.status);
```
</Tab>
<Tab value="Python">
```python
listed = client.accounts.list_accounts(profile_id=profile_id)

published = client.posts.create_post(
    content="Posted from your app.",
    platforms=[
        {"platform": a["platform"], "accountId": a["_id"]} for a in listed["accounts"]
    ],
    publish_now=True,
)

print(published["post"]["status"])
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/accounts?profileId=66a1f0c2a4b9d3e8f1a2b3c4" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"

curl -X POST "https://zernio.com/api/v1/posts" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Posted from your app.",
    "platforms": [{ "platform": "instagram", "accountId": "66b2e19d8c3f5a7e9d0b1c2d" }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

Response (`200`) from the list:

```json
{
  "accounts": [
    {
      "_id": "66b2e19d8c3f5a7e9d0b1c2d",
      "platform": "instagram",
      "username": "acmecorp",
      "isActive": true,
      "profileId": "66a1f0c2a4b9d3e8f1a2b3c4"
    }
  ]
}
```

Response (`201`) from the post:

```json
{
  "message": "Post published successfully",
  "post": {
    "_id": "65f1c0a9e2b5af0012ab34cd",
    "status": "published",
    "platforms": [
      { "platform": "instagram", "accountId": "66b2e19d8c3f5a7e9d0b1c2d", "status": "published" }
    ]
  }
}
```

<Callout type="warn">
`POST /v1/posts` accepts any `accountId` your team owns, whichever profile it sits in. Pass a customer only the account ids listed with their `profileId`.
</Callout>

## Step 4: Route webhooks to the customer

Webhook endpoints are stored per team (up to 50).

Run one endpoint and route by `profiles[]`. Or scope an endpoint to a set of profiles or accounts with `profileIds` / `accountIds` (below the table):

Every event that belongs to a profile carries a top-level `profiles` array with each profile's `id` and the `externalId` you set on it, so the customer is `profiles[0].externalId`:

```json
{
  "id": "0b6f7a2e-4c1d-4e8a-9f3b-2d5c6e7f8a9b",
  "event": "message.received",
  "timestamp": "2026-09-08T10:05:00Z",
  "profiles": [{ "id": "66a1f0c2a4b9d3e8f1a2b3c4", "externalId": "cus_8f3a2" }],
  "account": { "accountId": "66b2e19d8c3f5a7e9d0b1c2d", "platform": "instagram" }
}
```

- A post that targets accounts of several profiles lists each profile once.
- `externalId` is `null` on a profile you have not given one.
- Events that belong to no profile (verification, phone number stock, the API changelog, the test event) carry no `profiles` key.

When you route per account instead, the [webhooks overview](/webhooks#finding-the-account-an-event-is-about) lists where each event carries its account id.

To keep a set of customers on a separate endpoint instead, set `profileIds` (or `accountIds`) on that endpoint. Test tenants on staging are one example.

That endpoint then only receives events from those profiles or accounts. The [webhooks overview](/webhooks#routing-by-profile-or-account) has the details.

The [webhooks overview](/webhooks) covers delivery, retries and signatures. The [inbox guide](/multi-tenant/inbox) has a full handler.

## Step 5: Monitor account health

Tokens die when customers change passwords, revoke access or trip a platform security check.

Build the reconnect loop before launch:

1. Subscribe to [`account.disconnected`](/webhooks). Its `profiles[0].externalId` is the customer to notify and `account.accountId` the account to reconnect.
2. Prompt that customer to reconnect by starting a new [connect flow](/guides/connecting-accounts) with the same `profileId`.
3. Call [account health](/accounts/get-all-accounts-health) on a schedule to catch anything a webhook missed.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data: health } = await zernio.accounts.getAllAccountsHealth({
  query: { profileId, status: 'error' },
});

console.log(health.summary.needsReconnect);
```
</Tab>
<Tab value="Python">
```python
health = client.accounts.get_all_accounts_health(profile_id=profile_id, status="error")

print(health["summary"]["needsReconnect"])
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/accounts/health?profileId=66a1f0c2a4b9d3e8f1a2b3c4&status=error" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```
</Tab>
</Tabs>

Response (`200`):

```json
{
  "summary": { "total": 1, "healthy": 0, "warning": 0, "error": 1, "needsReconnect": 1 },
  "accounts": [
    {
      "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
      "platform": "instagram",
      "username": "acmecorp",
      "status": "error",
      "canPost": false,
      "tokenValid": false,
      "needsReconnect": true,
      "issues": ["Token expired"]
    }
  ]
}
```

## Rate limits with many customers

One API key covers every customer.

Your [rate limit](/guides/rate-limits) grows with your team's connected accounts, and all your customers share it.

Queue bursts per customer (a bulk import, a mass reply), so one customer cannot starve the rest. Webhooks replace most polling.

On a `429`, wait for the `Retry-After` header before retrying.

## Scoped API keys

An API key can reach every profile in your team by default.

To create a key that sees only one customer's profile, call `POST /v1/api-keys` with `scope: "profiles"` and `profileIds`. Add `permission: "read"` to make it read-only:

```bash
curl -X POST "https://zernio.com/api/v1/api-keys" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme-corp-readonly",
    "scope": "profiles",
    "profileIds": ["66a1f0c2a4b9d3e8f1a2b3c4"],
    "permission": "read"
  }'
```

Response (`201`):

```json
{
  "message": "API key created successfully",
  "apiKey": {
    "id": "6507a1b2c3d4e5f6a7b8c9d0",
    "name": "acme-corp-readonly",
    "key": "sk_...",
    "scope": "profiles",
    "profileIds": ["66a1f0c2a4b9d3e8f1a2b3c4"],
    "permission": "read"
  }
}
```

Use scoped keys for a per-customer backend service, a read-only analytics dashboard, or temporary access with `expiresIn` (days).

They are an access-control tool. The rate limit belongs to the team, so a scoped key adds no throughput.

**Resource groups.** To close off whole areas of the API rather than whole profiles, send `disabledResourceGroups` on the same call.

It is a denylist over ten groups: `publishing`, `engagement`, `messages`, `contacts`, `analytics`, `ads`, `telephony`, `accounts`, `billing`, `webhooks`. A per-customer backend that only schedules posts disables the other nine.

A key with any group disabled mints with a `zrk_` prefix instead of `sk_`. It refuses a call into a disabled group with `403`, `code: "insufficient_permissions"` and the `required_group` it wanted.

There is no update endpoint. To change the groups, create a second key and revoke the first.

The [Create API key endpoint](/api-keys/create-api-key) lists every field.

## What each customer costs you

Call `GET /v1/usage?range=cycle&groupBy=profile` for the current billing period's spend, split per profile.

`attribution.groups[]` carries one entry per profile id. `sum(groups) + unattributed` equals `totals` exactly, so a customer's share of your invoice is a lookup on their `profileId`.

Credits, 10DLC fees and Verify belong to no single profile and land in `unattributed`.

A profile-scoped key sees only its own profiles' groups, and says so with `attribution.restricted: true`.

[Billing](/pricing/billing) has the rest of the metering contract.

## Billing and suspension apply to the whole team

Profiles and scoped keys separate your customers' data and access. Billing, the rate limit and access to the API belong to your team.

When the team is paused, every profile and every key stops at once, profile-scoped keys included.

To bill or pause end customers separately, each one needs its own Zernio account: a user belongs to one team, and each team is billed on its own card.

### When a payment fails

1. Zernio first retries the charge on any other card saved on the team.
2. If that fails and your team has paid at least $50 to date, you get a 24-hour grace period: an email, and a dashboard banner with the amount due and the deadline. Adding or changing the card retries the charge right away. The deadline is not extended.
3. Without that payment history, or when the team has no card or an invalid billing address, the team is paused immediately.

While the team is paused:

- Every API call, reads included, answers `402` with `code: "PAYMENT_REQUIRED"` and a `billingUrl`.
- Scheduled posts that come due fail with a payment error and send `post.failed`. They are not retried after the pause ends; reschedule them.
- Connected accounts stay connected and keep their tokens, so nobody has to reconnect. Inbox polling and analytics syncs stop until access returns.

Teams still on a legacy Stripe plan have no grace period and do not get the `402`. Their scheduled posts fail with the payment error until the invoice is paid.

Access comes back on its own when a card is added or the open invoice is paid. Open invoices are charged, and the `402`s stop as soon as the charge succeeds.

### Other suspensions

A suspension for a breach of the [Terms](https://zernio.com/tos) also applies to the whole team and does not lift on payment. The Terms govern it, so contact support.

Problems on a single connected account stay on that account: a platform rate-limit cooldown or an expired token fails only that account's posts.

### Pausing one account

There is no paused state that keeps a connection without billing it.

`DELETE /v1/accounts/{accountId}` disconnects the account, revokes its token, removes it from the next daily billing count, and deletes its analytics data. The response carries `gracePeriodEndsAt`, one hour out.

- Reconnect the same platform account into the same profile before then, and it keeps its `accountId` and the scheduled posts that have not come due yet. Posts that come due while it is disconnected are not published to it, and reconnecting does not bring them back.
- After the grace period, a cleanup job deletes the account. Scheduled posts that target only this account are cancelled (`post.cancelled`); posts that also target other accounts drop this account and still publish to the others. A later reconnect gets a new `accountId`.

## Offboard a customer

1. [Disconnect their accounts](/accounts/delete-account). Active connected accounts block profile deletion with a `400`.
2. [Delete the profile](/profiles/delete-profile). Remaining disconnected accounts and provisioned WhatsApp numbers move to another of your profiles and are never deleted.

## If it fails

A `409` from Step 1 means you already have a profile with that `externalId` (`code: "profile_external_id_conflict"`) or with that name (`code: "profile_name_conflict"`):

```json
{
  "error": "A profile with this externalId already exists",
  "code": "profile_external_id_conflict",
  "param": "externalId",
  "details": { "existingProfileId": "66a1f0c2a4b9d3e8f1a2b3c4" }
}
```

Use `details.existingProfileId` as the customer's profile instead of creating another. This is what makes a signup retry safe: a create that timed out on your side and is sent again gets the first profile back.

A `402` with `code: "PAYMENT_REQUIRED"` is a billing gate on your team, so it affects every customer at once. Send yourself to its `dashboard_url` rather than retrying.

## Related

- [Publishing](/multi-tenant/publishing): retry-safe posting and per-profile queues.
- [Analytics dashboards](/multi-tenant/analytics): per-customer metrics from a sync worker.
- [Inbox and DMs](/multi-tenant/inbox): one inbox per customer, written by webhooks.
- [Connecting accounts](/guides/connecting-accounts): OAuth, headless mode and selection steps.
- [Webhooks](/webhooks): delivery, signatures and every event payload.