--- title: "Create a connect link" method: POST path: "/v1/platform-invites" tags: ["Connect"] --- # Create a connect link `POST /v1/platform-invites` ## Request - Base URL: `https://zernio.com/api` - URL: `https://zernio.com/api/v1/platform-invites` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Create a single-use link that lets someone else connect their account to one of your profiles, without a Zernio login. For Instagram, choose how they sign in with loginMethod. With facebook_login they sign in with Facebook and pick the Page linked to their Instagram account. ## Request body - object - `profileId` string, required: The profile the account is connected to. - `platform` 'facebook' | 'instagram' | 'linkedin' | 'twitter' | 'threads' | 'tiktok' | 'youtube' | 'pinterest' | 'reddit' | 'bluesky' | 'snapchat' | 'googlebusiness', required - `accountId` string: Reconnect this existing account instead of adding a new one. It must belong to the profile and platform. - `loginMethod` 'instagram_login' | 'facebook_login': Instagram only. instagram_login (the default) uses Instagram Login, facebook_login uses Facebook Login. A reconnect link keeps the method the account was connected with. - `expiresInDays` integer: Days until the link expires. ## Response `200` Connect link created - object - `invite` object - `_id` string - `platform` string - `loginMethod` 'instagram_login' | 'facebook_login' | 'null', nullable - `accountId` string, nullable - `expiresAt` string, date-time - `inviteUrl` string, uri ## Other responses - `400`: Invalid request - `401`: Missing or invalid API key. `code` is `missing_credentials` when no Authorization header was sent and `invalid_credentials` when the key is unknown, revoked or expired. - `403`: The API key is a restricted key (zrk_ prefix) and may not perform this operation. Three cases: 1. The operation's resource group (see the operation's x-resource-group) is disabled on the key. Fix: create a key with the group enabled in the dashboard API keys tab and revoke the old one. 2. The operation is admin-plane (x-resource-group admin-plane: API keys, invites, connected apps, member identity), never grantable to restricted keys. The error reads "Restricted API keys cannot manage API keys, invites, or member identity." Fix: a full-access key or the dashboard, never a new restricted key. 3. On webhook subscription writes, delivery-log reads and replays, a named event maps to a resource group the key does not hold. A restricted key can never create or edit a subscription broader than itself (a no-messages key cannot subscribe to, test-fire, redeliver or read logs for message.* events). - `404`: Resource not found - `429`: The connected account's upstream platform quota is exhausted. Behavior per platform: - **Reddit:** rate-limits per connected Reddit user (1000 requests per 10-minute window), shared by every operation on that account. Retry after the window resets; repeated calls while exhausted do not succeed and keep the budget spent. - **Google Ads:** writes and reports run on one developer token shared by every Google Ads account on Zernio. It holds Standard access (no daily operations cap), so this only happens when Google throttles the token or your ad account. - **Google Ads envelope:** `code: rate_limited`, `platform: google`, `details.quotaScope: DEVELOPER` (`ACCOUNT` when it is your own ad account's quota), `details.resetsAt` (ISO instant when Google accepts requests again) and `Retry-After` counting down to it. Retrying earlier cannot succeed. - **YouTube Analytics:** reads (channel-insights, demographics, daily-views, video-retention) use the "Queries per day" quota of the Google Cloud project the account is connected through, shared with other Zernio customers, so a 429 is not your own volume. Resets at midnight Pacific Time. - **YouTube Analytics envelope:** `code: rate_limited`, `platform: google`, `details.quotaExhausted: true`, `details.quotaScope: DEVELOPER`, `details.resetsAt` and `Retry-After` counting down to it. Retrying earlier cannot succeed. - **Meta ads:** every Meta throttle (codes 4, 17, 32, 613 and business-use-case codes 80000-80014) returns 429 `rate_limited`, even when Meta answers HTTP 400. `Retry-After` comes from Meta's `x-business-use-case-usage` estimate when sent, else Meta's 60-second minimum (30 seconds for the one-write-per-30-seconds limit on one object). - **Pinterest ads:** limits per user and app, per category (ads_read, ads_write, ads_analytics). `Retry-After` comes from Pinterest's `x-ratelimit-reset` when sent, otherwise 60 seconds. - **TikTok ads:** limits per app and per endpoint (per second, minute and day), answering overage with code 40100 or code 40002 `OVER_QPS_LIMIT`. Both return 429 `rate_limited` with `platform: tiktok` and `Retry-After: 10`. Space out bulk reads (e.g. one ad at a time per advertiser) instead of retrying at once. **TikTok Smart+ review read** (`GET /v1/ads/{adId}/tiktok-smart-plus-review`) has its own stricter TikTok quota. After an overage, Zernio answers 429 for that advertiser and connection without calling TikTok for about 60 seconds, then 120, up to 240 while TikTok keeps refusing, each with up to 10% random jitter. A successful call holds nothing back; the next overage pauses about 60 seconds again. `Retry-After` is the time left. The advertiser-wide read (`GET /v1/ads/tiktok-smart-plus-reviews`) answers 200 with `retryAfterSeconds` and `refreshState` instead. Keep one request in flight per advertiser there. ## Changes - **2026-11-10** `d568bb00ed73`: 15 info - added the optional property `docsUrl` to the response with the `400` status - added the optional property `docsUrl` to the response with the `401` status - added the optional property `docsUrl` to the response with the `429` status - added the optional property `provider` to the response with the `400` status - …11 more - **2026-11-04** `b8e3341e6fee`: 1 info - endpoint added [Operation history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/platform-invites/post.md) --- [API](https://skmtc.dev/zernio/apis/zernio-api.md) - [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/a79c233ebf22?raw)