openapi: 3.1.0 info: title: Zernio API version: "1.0.4" description: | API reference for Zernio. Authenticate with a Bearer API key. Base URL: https://zernio.com/api termsOfService: https://zernio.com/tos contact: name: Zernio Support url: https://zernio.com email: support@zernio.com # RapidAPI extensions for Hub listing x-logo: url: https://zernio.com/icon.png?v=3 x-long-description: | Zernio is the social media API that replaces 16 integrations. Schedule posts, retrieve analytics, manage DMs, comments, and reviews across Twitter/X, Instagram, WhatsApp, TikTok, LinkedIn, Facebook, YouTube, Threads, Reddit, Pinterest, Bluesky, Telegram, Google Business, Snapchat, Discord, and Slack, all from a single REST API. Run paid ads on Meta (Facebook + Instagram), Google, TikTok, LinkedIn, Pinterest, X, and OpenAI from the same account. Key features: Unified posting to 16 platforms, ads management on 7 ad networks (via /v1/ads), aggregated analytics, unified inbox (DMs, comments, reviews), webhooks, OAuth connect, queue scheduling, and white-label support for agencies managing unlimited accounts. Supported posting platforms: Twitter/X, Instagram, WhatsApp, Facebook, LinkedIn, TikTok, YouTube, Pinterest, Reddit, Bluesky, Threads, Google Business, Telegram, Snapchat, Discord, Slack. Supported ad platforms: Meta Ads, Google Ads, TikTok Ads, LinkedIn Ads, Pinterest Ads, X Ads, OpenAI Ads. x-category: Social x-website: https://zernio.com x-thumbnail: https://rapidapi-prod-apis.s3.amazonaws.com/b24d3df5-563c-4a50-9e1e-1ad3eb1fce69.png x-version-lifecycle: ACTIVE x-badges: - name: "social media" value: "social media" - name: "scheduling" value: "scheduling" - name: "instagram" value: "instagram" - name: "tiktok" value: "tiktok" - name: "twitter" value: "twitter" - name: "linkedin" value: "linkedin" - name: "facebook" value: "facebook" - name: "youtube" value: "youtube" - name: "social media api" value: "social media api" - name: "posting" value: "posting" # RapidAPI Hub documentation tab (README) x-documentation: readme: | # Zernio API The social media API that replaces 14 integrations. Build social media features into your app in minutes, not months. ## Quick Start **Base URL:** `https://zernio.com/api/v1` **Authentication:** All requests require a Bearer API key in the `Authorization` header. ```bash curl https://zernio.com/api/v1/user \ -H "Authorization: Bearer YOUR_API_KEY" ``` Get your API key at [zernio.com/dashboard/api-keys](https://zernio.com/dashboard/api-keys). ## Core Concepts | Concept | Description | |---------|-------------| | **Profiles** | Containers that organize social accounts into brands or projects | | **Accounts** | Connected social media accounts belonging to a profile | | **Posts** | Content scheduled or published to one or more accounts | | **Queue** | Recurring time slots for automatic post scheduling | ## Create a Post ```bash curl -X POST https://zernio.com/api/v1/post \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "profileId": "your-profile-id", "text": "Hello from Zernio API!", "socialAccountIds": ["account-1", "account-2"], "scheduledAt": "2025-01-15T10:00:00Z" }' ``` This single call publishes or schedules the post to all selected accounts across any platform. ## Supported Platforms | Platform | Post | Stories/Reels | Analytics | Inbox | |----------|------|---------------|-----------|-------| | Twitter/X | Yes | - | Yes | Yes | | Instagram | Yes | Yes | Yes | Yes | | Facebook | Yes | Stories | Yes | Yes | | LinkedIn | Yes | - | Partial | - | | TikTok | Yes | - | Yes | - | | YouTube | Yes | Shorts | Yes | Yes | | Pinterest | Yes | - | Yes | - | | Reddit | Yes | - | - | Yes | | Bluesky | Yes | - | - | Yes | | Threads | Yes | - | Yes | Yes | | Google Business | Yes | - | - | Yes | | Telegram | Yes | - | - | - | | Snapchat | Yes | - | - | - | > **LinkedIn Analytics Note:** For personal LinkedIn accounts, analytics are only available for posts published through Zernio. This is a LinkedIn API limitation: the `memberCreatorPostAnalytics` endpoint only returns metrics for posts authored by the authenticated user. Company/organization page analytics are not affected and work for all posts. > **Google Business Analytics Note:** Per-post analytics for Google Business Profile are deprecated by Google with no replacement, so Google Business posts always report `syncStatus: "unavailable"` with an explanatory `errorMessage`. Location-level metrics (impressions, clicks, calls, directions, bookings) are available via the dedicated `/v1/analytics/googlebusiness/performance` endpoint. ## Rate Limits API request throughput is rate-limited per minute on a sliding window. Limits scale with your team's total connected social accounts: - **0–2 accounts** (free tier): 60 req/min - **3–2,000 accounts**: 600 req/min - **2,001+ accounts**: 1,200 req/min Legacy AppSumo lifetime tiers get a flat 600 req/min regardless of tier. Posts themselves are unlimited on every connected social account; the rate limit applies only to API request throughput. Zernio also applies per-account daily publish caps as an anti-abuse safeguard (Instagram 100/day, Facebook 100/day, Threads 250/day, X/Twitter 50/day, Pinterest 25/day, 50/day for every other platform), plus a 25-posts-per-hour per-account velocity cap. All responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers — read these instead of hard-coding limits, since your tier may be configured higher than the default. ## Webhooks Receive real-time notifications for post status changes, account events, and incoming messages: - `post.scheduled` - Post entered the scheduled state: created with a schedule, added to a queue, a draft promoted to scheduled or queued, a failed post retried, or a recycled clone created - `post.published` - Post successfully published - `post.failed` - Post failed on all platforms - `post.partial` - Post published to some platforms, failed on others - `post.cancelled` - Post publishing was cancelled - `post.recycled` - Post recycled (cloned and re-scheduled) - `post.platform.published` - A single platform target inside a post finished publishing successfully. Fires once per platform-account as it terminates, without waiting for other platforms on the same post. Use this for incremental UIs; use `post.published` for the post-level rollup. - `post.platform.failed` - A single platform target inside a post failed permanently. Temporary/retryable failures do NOT fire this event, only permanent ones, so retry loops stay quiet. - `post.platform.deleted` - A single platform target inside a post was detected as deleted on the platform after publishing (e.g. the user deleted the Instagram post natively). Detection is poll-driven via Zernio background sync (~hourly), not real-time. `platform.deletedAt` carries the detection time. Coverage is bounded to the posts the platform listing returns. - `post.tiktok.url_resolved` - A published TikTok post's public URL became available. TikTok exposes the numeric video id asynchronously, so `post.published` / `post.platform.published` can carry an empty `publishedUrl` for TikTok; this event delivers the URL once resolved (at most once per platform target). Never fires for drafts or private posts, which have no public URL. - `post.external.created` - A native post authored outside Zernio (e.g. a Google Business Profile localPost created in the Google UI) was detected by our sync for the first time. Poll-driven (~hourly), not real-time. Payload carries `post.source: "external"`. - `post.external.updated` - A tracked native post's text or media changed on the platform. Edits are detected by comparing text/media structure and (where the platform exposes it) the platform's own edit timestamp; media-URL-only refreshes do not fire this. - `post.external.deleted` - A tracked native post was detected as removed from the platform. `post.deletedAt` carries the detection time. Coverage is bounded to the most recent posts the platform listing returns. - `account.connected` - Social account connected - `account.disconnected` - Social account disconnected (token expired) - `account.ads.initial_sync_completed` - Initial ads sync (discovery + 90-day backfill) completed for an ads-enabled account - `message.received` - New DM received - `conversation.started` - A new conversation opened between one of your accounts and a contact, in either direction (any DM platform); fires only the first time the thread appears - `message.sent` - DM sent via the API - `message.edited` - A sender edited a message (Instagram, Messenger, Telegram) - `message.deleted` - A sender deleted ("unsent") a message (Instagram; WhatsApp when the business deletes a sent message) - `message.delivered` - An outgoing message was delivered (WhatsApp, Messenger) - `message.read` - An outgoing message was read by the recipient (WhatsApp, Messenger, Instagram) - `message.failed` - An outgoing message failed delivery (WhatsApp) - `reaction.received` - A participant added or removed an emoji reaction on a message (WhatsApp, Telegram, Slack, Instagram, Facebook Messenger) - `comment.received` - New comment received on a post - `review.new` - New review posted on a connected account (Google Business Profile) - `review.updated` - Review updated or reply added (Google Business Profile, or via reply API) - `lead.received` - New lead submitted against a Meta Lead Gen (Instant) Form. `lead.fields` is the question-key → answer map; `lead.formId`/`lead.adId` give provenance. - `ad.status_changed` - Ad, ad set, or campaign changed status on the ad platform (Meta: `in_process_ad_objects` entry/exit and `with_issues_ad_objects` violations) - `whatsapp.template.status_updated` - WhatsApp Business template completed (re)review by Meta. `template.status` carries the new state (APPROVED, REJECTED, PENDING, PAUSED, DISABLED, IN_APPEAL, PENDING_DELETION); `template.reason` is Meta's free-form reason or "NONE". - `call.received` - An inbound call (phone/PSTN or WhatsApp) reached one of your numbers and was routed to its destination - `call.ended` - A call ended; carries duration, end reason, cost breakdown, and the recording when enabled - `call.failed` - A call failed with a hard error before or during bridging - `call.permission_request` - A WhatsApp user accepted or rejected your call-permission request - `whatsapp.automatic_event` - Meta's automatic event identification detected a lead or purchase in a Click-to-WhatsApp conversation. Branch on `eventName` (`LeadSubmitted` | `Purchase`); carries the `ctwa_clid` Conversions API match key - `whatsapp.number.kyc_submitted` - An end customer completed a hosted KYC share link; the number entered regulatory review under your account - `whatsapp.number.activated` - A provisioned WhatsApp number finished setup and is ready to connect - `whatsapp.number.declined` - A regulated number order was declined in review; nothing activates and nothing is billed - `whatsapp.number.action_required` - The regulator asked for more information on a placed number order; the order stays pending until provided - `whatsapp.number.verification_required` - A regulated number needs end-user ID verification; carries the link to forward - `whatsapp.number.suspended` - An active number was suspended (e.g. failed payment); carries a `reason` - `whatsapp.number.reactivated` - A suspended number is usable again - `whatsapp.number.released` - A number was released and is no longer usable (terminal); carries a `reason` - `verification.approved` - A managed-OTP verification was approved (the user submitted the correct code) - `verification.failed` - A managed-OTP verification was exhausted after too many wrong code attempts - `webhook.test` - Test event sent when verifying a webhook endpoint Webhook payloads are signed with HMAC-SHA256 via the `X-Zernio-Signature` header. ## Full Documentation For complete guides, platform-specific details, and SDK references, visit [docs.zernio.com](https://docs.zernio.com). ## SDKs Official SDKs available for: [Node.js](https://www.npmjs.com/package/@zernio/node), [Python](https://pypi.org/project/zernio-sdk), Go, Ruby, Java, PHP, .NET, and Rust. servers: - url: https://zernio.com/api description: Production - url: http://localhost:3000/api description: Local tags: - name: Posts description: | Create, schedule, list, update, and delete posts across all connected social accounts. - name: Users description: | Read the authenticated user and team members. - name: Usage description: | Usage and metering. `GET /v1/usage` is dual-mode: bare calls return the plan / quota snapshot (back-compat, same as `/v1/usage-stats`); calls with `range` / `granularity` params return usage METERING — billed spend (USD) by product family (accounts, numbers, calls, sms, dlc, xApi, credits) over any window, from Metronome's invoice breakdown (also served at `GET /v1/usage/daily`). The `/v1/usage/` spokes (calls, sms) meter per-domain consumption volumes over a window. `GET /v1/billing` is the billing statement (balance, credits, caps, payment status). - name: Profiles description: | Manage profiles (named groups of social accounts). - name: Accounts description: | Manage connected social media accounts: list, fetch, update, disconnect, and read account health. - name: Account Groups description: | Manage account groups (collections of accounts used for cross-posting and organization). - name: API Keys description: | Create, list, and revoke API keys used to authenticate requests. Resource groups. A key can opt out of any of the ten groups (publishing, engagement, messages, contacts, analytics, ads, telephony, accounts, billing, webhooks) via `disabledResourceGroups` at creation. Omit the field for a legacy full-access key. A key with any group disabled mints with the `zrk_` prefix, is refused on operations in those groups with 403 `insufficient_permissions` plus `required_group`, and can never manage API keys, invites, connected apps, or member identity. Each operation publishes its group as `x-resource-group`. There is no update endpoint: duplicate the key with different groups and revoke the old one. - name: Connected Apps description: | List and revoke the OAuth clients (AI assistants and MCP connectors) authorized on the account. Connector tokens resolve against the same resource-group registry as API keys, but there is no way to narrow a connector's groups yet. Treat an authorized connector as full account access and revoke it if that is not what you want. - name: Invites description: | Generate invite tokens for adding members to a team. - name: Connect description: | OAuth and credential flows for connecting social accounts, plus per-platform selection steps (Facebook pages, Pinterest boards, LinkedIn organizations, GMB locations, etc.). - name: Media description: | Upload and presign media (images, videos, documents) for use in posts. - name: Reddit Search description: | Search Reddit posts and browse subreddit feeds. - name: GMB Reviews description: | Google Business Profile reviews: list reviews and reply to them. - name: GMB Food Menus description: | Read and update Google Business Profile food menus. - name: GMB Location Details description: | Read and update Google Business Profile location details. - name: GMB Media description: | Manage Google Business Profile media (photos and videos): list, upload, and delete. - name: GMB Attributes description: | Read and update Google Business Profile attributes. - name: GMB Place Actions description: | Manage Google Business Profile place action links (booking, ordering, reservations, etc.). - name: Discord description: | Discord-specific endpoints for managing webhook identity (display name and avatar), switching channels, and listing guild channels. - name: LinkedIn Mentions description: | Resolve LinkedIn organization and person mentions for use in posts. - name: Instagram description: | Instagram-specific read endpoints: list a connected account's Stories and fetch per-Story insights. All endpoints require an accountId parameter identifying the Instagram-connected social account. - name: Queue description: | Manage posting-queue time slots and preview the upcoming queue. - name: Analytics description: | Post and account analytics across platforms (insights, demographics, follower history, best time to post, content decay, and aggregated metrics). - name: Inbox Access description: | Check and manage inbox feature access. - name: Messages description: | Unified inbox API for managing conversations and direct messages across all connected accounts. All endpoints aggregate data from multiple social accounts in a single API call. Requires Inbox addon. - name: Comments description: | Unified inbox API for managing comments on posts across all connected accounts. Supports commenting on third-party posts for platforms that allow it (YouTube, Twitter, Reddit, Bluesky, Threads). All endpoints aggregate data from multiple social accounts in a single API call. Requires Inbox addon. - name: Reviews description: | Unified inbox API for managing reviews on Facebook Pages and Google Business accounts. All endpoints aggregate data from multiple social accounts in a single API call. Requires Inbox addon. - name: Mentions description: | Unified inbox API for managing mentions across connected accounts. Currently supports LinkedIn organization mentions. Requires Inbox addon. - name: Twitter Engagement description: | X/Twitter-specific engagement endpoints for retweeting, bookmarking, and following. Rate limits: 50 requests per 15-min window per user. Retweets share the 300/3hr creation limit with tweet creation. - name: Validate description: | Pre-flight validation endpoints. Check post content, character limits, media URLs, and subreddit existence before publishing. - name: Account Settings description: | Platform-specific account settings: Facebook persistent menu, Instagram ice breakers, and Telegram bot commands. - name: Contacts description: | Cross-platform contact management (CRM). Contacts are unified identities linked to platform-specific channels (phone, IGSID, etc.). Created automatically when messages arrive, or manually via API. - name: Custom Fields description: | Custom field definitions for contacts. Define fields (text, number, date, boolean, select) that can be set on any contact for segmentation and personalization. - name: Broadcasts description: | Platform-agnostic broadcast campaigns. Send bulk messages to contacts via any inbox platform. WhatsApp broadcasts use templates; other platforms use generic messages. - name: Sequences description: | Drip campaign sequences. Send a series of messages to enrolled contacts with configurable delays between steps. Supports auto-exit on reply or unsubscribe. - name: Workflows description: | Branching conversation automations. An inbound message matches a workflow's trigger and walks a directed graph of nodes (send message, wait for reply, condition, set variable, delay, webhook, handoff, end). Unlike Sequences (linear, time-based drips), Workflows are event-driven and interactive. Fully supported on WhatsApp, Instagram, and Messenger; `send_message` template and interactive modes are WhatsApp-only. - name: Comment Automations description: | Comment-to-DM growth automations. Set up keyword triggers on Instagram/Facebook so commenters automatically receive a DM. Scope per post or account-wide (omit `platformPostId` to match comments on every post on the account, with unlimited automations stacked per account). Supports dedup, optional public comment reply, and auto-creates contacts. - name: Ad Campaigns description: | The advertising structure: campaigns, ad sets, and ads. Create standalone campaigns/ads, boost an organic post, duplicate at any level, pause/resume, and read the full tree and timeline. Campaigns are virtual aggregations of ads grouped by their platform campaign ID. Per-operation platform support is shown by the platform badges. Requires the Ads add-on. - name: Ad Creatives description: | Creative assets: the standalone creative library (create/reuse/rename), the ad-account image library (list + base64 upload), rendered ad previews, and product catalogs for Advantage+/dynamic ads. Meta only. Requires the Ads add-on. - name: Ad Audiences description: | Custom audiences for targeting: customer lists (hashed upload), website + engagement + lookalike audiences, and reusable saved-targeting presets. Creation support varies by platform (badges show which); LinkedIn adds company-list and engagement segments. Requires the Ads add-on. - name: Ad Targeting description: | Targeting discovery: search interests/behaviors/geo/demographics, estimate reach, and (LinkedIn) bid pricing and supply forecasts. Feeds the targeting fields on create. Requires the Ads add-on. - name: Ad Insights description: | Measurement: cached aggregate analytics per ad/campaign, plus live Meta Graph insight queries (arbitrary fields, breakdowns, filtering, attribution windows) and async report runs. Requires the Ads add-on. - name: Conversions description: | Server-side Conversions API: send + adjust conversion events (with hashed matching and consent/LDU forwarding), read Event Match Quality, and manage conversion destinations (pixels/datasets) and their ad-account associations. Supported on Meta, Google, TikTok and LinkedIn (badges show per operation). Requires the Ads add-on. - name: Messaging Ads description: | Click-to-message and click-to-call destination ads: WhatsApp (CTWA), Messenger, Instagram Direct, and Call ads. Meta only. Requires the Ads add-on. - name: Reach and Frequency description: | Fixed-price reserved (Reach & Frequency) buying: quote a prediction, reserve price + inventory, and buy via a RESERVED campaign. Meta only. Requires the Ads add-on. - name: Lead Gen description: | Instant lead forms on Facebook Pages: create/list/archive forms and retrieve (or test) their leads. Meta only. Requires the Ads add-on. - name: Ad Accounts description: | Ad accounts and operational/diagnostic reads: list accounts, account finances, change/audit log, A/B studies, high-demand periods, ad labels, DSA defaults + recommendations, and Business Managers (Meta) / Business Centers (TikTok). Requires the Ads add-on. - name: Tracking Tags description: | Manage the platform measurement tag — the thing you create, install on a website, send events to, and target ads against. On Meta this is a Pixel; the surface is platform-neutral so other platforms (Pinterest Tag, LinkedIn Insight Tag, etc.) can be added without changing the contract. Create a tag, get it (including the install code snippet), rename + adjust matching/cookie/data-use settings, share it with ad accounts, and read aggregated event stats. Currently Meta-only. Requires the Ads add-on. - name: Webhooks description: | Configure webhooks for real-time notifications. Webhooks can be created from the dashboard (Settings → Webhooks) or via this API. Events: post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled, post.platform.published, post.platform.failed, post.platform.deleted, post.tiktok.url_resolved, post.external.created, post.external.updated, post.external.deleted, account.connected, account.disconnected, account.ads.initial_sync_completed, message.received, conversation.started, call.received, call.ended, call.failed, call.permission_request, message.sent, message.edited, message.deleted, message.delivered, message.read, message.failed, reaction.received, comment.received, review.new, review.updated, lead.received, ad.status_changed, whatsapp.template.status_updated, whatsapp.automatic_event, whatsapp.number.activated, whatsapp.number.declined, whatsapp.number.action_required, whatsapp.number.verification_required, whatsapp.number.suspended, whatsapp.number.reactivated, whatsapp.number.released, whatsapp.number.kyc_submitted, verification.approved, verification.failed, webhook.test. Security: optional HMAC-SHA256 signature in X-Zernio-Signature header. Configure a secret key to enable verification. Custom headers supported. Resource groups. Every event belongs to one group: post.* to publishing, message.*, reaction.*, conversation.*, call.* and whatsapp.automatic_event to messages, comment.* and review.* to engagement, lead.* to contacts, ad.* to ads, account.* and whatsapp.template.* to accounts, whatsapp.number.* and verification.* to telephony, webhook.test to webhooks. Two independent controls use that mapping. (1) A restricted (zrk_) API key can only subscribe to, test-fire, redeliver, or read delivery logs for events in the groups it holds, so it can never create a subscription broader than itself. (2) Each subscription carries its own `disabledResourceGroups` denylist: events in a disabled group are dropped before delivery to that endpoint, on live delivery and on every replay path, no matter which key or session created the subscription. Changing that denylist applies to every event emitted after the change; events already queued when it landed can still be delivered for up to five minutes after they were enqueued, because the delivery worker trusts a five-minute enqueue-time snapshot before re-checking. Absent or empty on a subscription means it receives everything it subscribes to, which is the behavior of every subscription created before the field existed. - name: Webhook Events description: | Incoming webhook deliveries sent by Zernio to your configured endpoint URL. - name: Logs description: | Publishing logs for transparency and debugging. Each log includes the platform API endpoint, HTTP status code, request/response bodies, duration, and retry attempts. Logs are automatically deleted after 7 days. - name: WhatsApp description: | WhatsApp Business API. Template, business profile, and phone number endpoints. All endpoints require an accountId parameter identifying the WhatsApp-connected social account. - name: WhatsApp Calling description: | Voice calling over the WhatsApp Business API: enable/disable calling on a number, configure call hours and permissions, and place or list calls. All endpoints require an accountId parameter identifying the WhatsApp-connected social account. - name: WhatsApp Templates description: | Browse Meta's pre-approved WhatsApp template library. Use these read-only lookups to discover library templates you can import as your own message templates. All endpoints require an accountId parameter identifying the WhatsApp-connected social account. - name: WhatsApp Flows description: | WhatsApp Flows let you build native interactive forms, surveys, and booking experiences inside WhatsApp. Flows are created in DRAFT status, populated with a Flow JSON definition, then published for sending. Published flows are immutable; to update, create a new flow (optionally cloning the old one). All endpoints require an accountId parameter identifying the WhatsApp-connected social account. - name: Phone Numbers description: | Buy and manage phone numbers. A phone number is a platform-independent unit; WhatsApp, SMS, and Voice are features you enable on it. Purchase, search inventory, complete country KYC, and release numbers here; turn features on via the per-number sub-resources (`/v1/phone-numbers/{id}/voice`, `/sms`, `/whatsapp/...`). Requires a paid plan. - name: Verify description: | Managed one-time passcodes (OTP) for phone verification. Two calls handle the whole lifecycle: create a verification (we generate the code, deliver it by SMS from a phone number on your account, and store only its hash) and check the code the user typed. Usage-based billing only. - name: WhatsApp Phone Numbers description: | Deprecated namespace: phone numbers moved to `/v1/phone-numbers` (a number is platform-independent; WhatsApp is one feature on it). These aliases keep working with the same contracts, but new integrations should use the Phone Numbers endpoints. - name: WhatsApp Sandbox description: | Shared WhatsApp sandbox: a Zernio-owned WhatsApp number every user can test against without provisioning their own. Send the verified sandbox template to phones you activate via a reply-based verification flow. Designed for testing message flows, bot replies, and webhook payloads end-to-end with zero number-purchase overhead. - name: Calls description: | Unified call history across every number you own: WhatsApp Business Calling and regular phone (PSTN) calls in one list, newest first, without fanning out one request per number. Each row carries `channel` and `accountId` so you can fetch details and recordings from the matching channel-specific endpoint. Private beta: returns 403 unless your account is enrolled. - name: Voice description: | Regular phone (PSTN) calling on your numbers. Enable voice on a number and route inbound calls to your own AI voice agent (Vapi/Retell), a phone, or a SIP endpoint, with voicemail, business-hours routing, IVR, recording, and transcription. Place outbound calls, manage live ones (end, blind-transfer), resolve recordings, and drive the browser softphone. Private beta: returns 403 unless your account is enrolled. - name: SMS description: | SMS/MMS on your numbers: enable SMS on a number, send messages, validate recipient numbers, export STOP opt-outs, and complete the US carrier registration (10DLC or toll-free) required before US traffic delivers. Private beta: returns 404 unless your account is enrolled. components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: API key authentication - use your Zernio API key as a Bearer token connectToken: type: apiKey in: header name: X-Connect-Token description: | Short-lived connect token for API users during OAuth flows. Automatically generated when initiating OAuth without a browser session. Valid for 15 minutes. Used to authenticate Facebook page selection API calls. parameters: PageParam: name: page in: query description: Page number (1-based) schema: { type: integer, minimum: 1, default: 1 } IdempotencyKeyHeader: name: Idempotency-Key in: header required: false schema: { type: string, maxLength: 255 } description: >- Optional client-generated unique key (e.g. a UUID) that makes retries safe. Same key + same body replays the original response; same key + different body → 422; key still processing → 409. responses: IdempotencyKeyInFlight: description: Same Idempotency-Key still processing; retry after a short backoff IdempotencyKeyReused: description: Idempotency-Key reused with a different body BadRequest: description: Invalid request content: application/json: schema: { $ref: '#/components/schemas/ErrorResponse' } Unauthorized: description: Unauthorized content: application/json: schema: type: object properties: error: type: string example: Unauthorized NotFound: description: Resource not found content: application/json: schema: type: object properties: error: type: string example: Not found ResourceGroupForbidden: description: >- 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 it by creating a key with the group enabled in the dashboard API keys tab and revoking the old one. (2) The operation is admin-plane (x-resource-group admin-plane: API keys, invites, connected apps, member identity), which is never grantable to restricted keys; the error reads "Restricted API keys cannot manage API keys, invites, or member identity." and the fix is 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, so 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). content: application/json: schema: type: object properties: error: type: string example: "This API key has the 'messages' resource group disabled. GET /api/v1/inbox/conversations requires it. Create a key with 'messages' enabled in the dashboard API keys tab." code: type: string enum: [insufficient_permissions, unclassified_resource] required_group: type: string description: 'The resource group the key needs for this operation. Absent on admin-plane and unclassified-path denials.' enum: [publishing, engagement, messages, contacts, analytics, ads, telephony, accounts, billing, webhooks] RateLimited: description: | The connected account's upstream platform quota is exhausted. Reddit rate-limits per connected Reddit user (1000 requests per 10-minute window), and that budget is shared by every operation using that account. Retry after the window resets rather than retrying immediately; repeated calls while exhausted do not succeed and keep the budget spent. headers: Retry-After: description: 'Seconds remaining until the upstream quota resets.' schema: { type: integer } content: application/json: schema: { $ref: '#/components/schemas/ErrorResponse' } PaymentRequired: description: | Payment method or enterprise contract required. The authenticated account hit a billing gate before the connection could proceed. Three reasons: - `free_tier_exceeded`: the team has connected more accounts than the free tier allows. Add a payment method on the dashboard to continue (the user will be billed per additional connected account). - `twitter_passthrough`: connecting an X (Twitter) account requires a card on file from day one because X API calls incur real per-call pass-through costs. Applies to the 1st X account, not just the 3rd+. - `enterprise_required`: the team is on an enterprise contract with a negotiated connected-account cap and has reached it. Self-service teams have NO connection cap (the $1/account rate continues at any scale), so this reason can only fire for teams whose contract sets an explicit limit. `dashboard_url` deep-links to the enterprise contact page rather than the billing tab. The end-user already has a card on file; this gate is about contract terms, not card collection. SDK consumers should switch on `reason` to render the right prompt. For `free_tier_exceeded` and `twitter_passthrough`, redirect the end-user to `dashboard_url` to add a payment method via Zernio's hosted Stripe Setup Checkout. For `enterprise_required`, redirect to `dashboard_url` (the enterprise contact form) to adjust the contract's limit. content: application/json: schema: type: object required: [error, code, reason] properties: error: type: string description: Human-readable error message suitable for end-user display. example: 'X (Twitter) requires a payment method due to API pass-through costs. Add a payment method to connect an X account.' code: type: string enum: [PAYMENT_REQUIRED] description: Machine-readable error code. Stable across versions. reason: type: string enum: [free_tier_exceeded, twitter_passthrough, enterprise_required] description: Discriminator for which gate fired. documentation_url: type: string format: uri description: Link to the relevant documentation page. example: https://docs.zernio.com/billing/payment-method-required dashboard_url: type: string format: uri description: | Deep-link to send the end-user to. For `free_tier_exceeded` and `twitter_passthrough` this is the Zernio billing tab. For `enterprise_required` this is the Zernio enterprise contact page. example: https://zernio.com/dashboard?tab=billing details: type: object description: Structured context for SDK clients that want to render their own UX. Keys vary by `reason`. properties: free_tier_account_limit: type: integer description: How many accounts the free tier allows. Only set when reason=free_tier_exceeded. example: 2 current_account_count: type: integer description: How many accounts the team currently has connected. Set when reason=free_tier_exceeded or reason=enterprise_required. example: 5 has_payment_method: type: boolean description: Whether the team currently has a card on file in Stripe. Set when reason=free_tier_exceeded or reason=twitter_passthrough. effective_account_limit: type: integer description: | The negotiated connected-account cap from the team's enterprise contract. Self-service teams have no cap and never receive this reason. Only set when reason=enterprise_required. example: 2000 examples: freeTierExceeded: summary: Free tier exceeded (no card on file) value: error: 'Add a payment method to connect more than 2 accounts.' code: PAYMENT_REQUIRED reason: free_tier_exceeded documentation_url: https://docs.zernio.com/billing/payment-method-required dashboard_url: https://zernio.com/dashboard?tab=billing details: free_tier_account_limit: 2 current_account_count: 3 has_payment_method: false twitterPassthrough: summary: Connecting first X account without a card value: error: 'X (Twitter) requires a payment method due to API pass-through costs. Add a payment method to connect an X account.' code: PAYMENT_REQUIRED reason: twitter_passthrough documentation_url: https://docs.zernio.com/billing/payment-method-required dashboard_url: https://zernio.com/dashboard?tab=billing details: has_payment_method: false enterpriseRequired: summary: Team reached the negotiated cap on its enterprise contract value: error: 'You have 2000 connected accounts, which reaches the 2,000-account limit on your contract. Contact us to raise it.' code: PAYMENT_REQUIRED reason: enterprise_required documentation_url: https://docs.zernio.com/billing/payment-method-required dashboard_url: https://zernio.com/enterprise details: effective_account_limit: 2000 current_account_count: 2000 schemas: Verification: type: object description: 'A managed OTP verification. The code itself is never returned or stored (hash only).' properties: id: { type: string } status: { type: string, enum: [pending, approved, expired, max_attempts_reached, canceled, delivery_failed] } channel: { type: string, enum: [sms] } to: { type: string } expiresAt: { type: string, format: date-time } attempts: { type: integer } maxAttempts: { type: integer } sendCount: { type: integer, description: 'Accepted deliveries (initial send + resends); each bills one verification fee.' } lastSentAt: { type: [string, "null"], format: date-time } createdAt: { type: string, format: date-time } resend: { type: boolean, description: 'Present on create responses: true when an active verification was resent instead of created.' } RfPrediction: type: object description: A Meta Reach & Frequency prediction. Money values in whole units of the ad account currency. properties: predictionId: { type: string } status: { type: string, description: "ready | pending | failed:" } budget: { type: [number, "null"], description: "Quoted (or provided) lifetime budget for the window." } reach: { type: [integer, "null"], description: "Predicted (or requested) unique reach." } impressions: { type: [integer, "null"] } minBudget: { type: [number, "null"], description: "Meta's allowed lower bound for this spec." } maxBudget: { type: [number, "null"] } minReach: { type: [integer, "null"] } maxReach: { type: [integer, "null"] } frequencyCap: { type: [integer, "null"] } startTime: { type: [integer, "null"], description: "Unix seconds; the reserved window the R&F ad set will run on." } stopTime: { type: [integer, "null"] } expiresAt: { type: [string, "null"], description: "When the reservation's locked price expires (set after reserving)." } CtwaAdRequestBody: type: object required: [accountId, adAccountId, name] description: | In addition to the `required` list, the request must use EXACTLY ONE of the two shapes: - Single-creative: `headline`, `body`, and one of `imageUrl` / `video` (mutually exclusive). - Multi-creative: a non-empty `creatives[]` array. Top-level `headline` / `body` / `imageUrl` / `video` must NOT be set on this shape. The route enforces this at the Zod boundary; OpenAPI's `required` cannot express the OR cleanly. properties: accountId: type: string minLength: 1 description: Facebook or Instagram SocialAccount ID. adAccountId: type: string minLength: 1 description: Meta ad account ID, e.g. `act_123456789`. name: type: string minLength: 1 description: | Ad display name. Used to derive campaign / ad set names. On the multi-creative shape, each ad's Meta name gets a " #N" suffix (1-indexed) so Ads Manager shows them as a numbered batch. headline: type: string minLength: 1 maxLength: 255 description: | Single-creative shape only. Mutually exclusive with `creatives[]`. body: type: string minLength: 1 description: | Primary text shown above the image / video. Single-creative shape only. Mutually exclusive with `creatives[]`. imageUrl: type: string format: uri description: | Image asset for single-creative shape. Mutually exclusive with `video` and with `creatives[]`. Required on the single-creative shape if `video` is not supplied. video: type: object required: [url, thumbnailUrl] properties: url: { type: string, format: uri } thumbnailUrl: type: string format: uri description: | Required by Meta for every video creative. Used as the ad thumbnail. description: | Video creative for single-creative shape. Mutually exclusive with `imageUrl` and with `creatives[]`. Required on the single-creative shape if `imageUrl` is not supplied. creatives: type: array minItems: 1 description: | Multi-creative shape: N CTWA ads under one campaign + one ad set, sharing budget and targeting. Mutually exclusive with the top-level single-creative fields (`headline` / `body` / `imageUrl` / `video`). Each entry must supply its own headline, body, and exactly one of `imageUrl` / `video`. items: type: object required: [headline, body] description: | Each entry must also include exactly one of `imageUrl` or `video`. properties: headline: type: string minLength: 1 maxLength: 255 body: type: string minLength: 1 description: Primary text shown above the image / video. imageUrl: type: string format: uri description: | Image asset. Mutually exclusive with this entry's `video`. Required if `video` is not supplied. video: type: object required: [url, thumbnailUrl] properties: url: { type: string, format: uri } thumbnailUrl: type: string format: uri description: | Required by Meta for every video creative. Used as the ad thumbnail. description: | Video creative. Mutually exclusive with this entry's `imageUrl`. Required if `imageUrl` is not supplied. adSetId: type: string description: | Attach the creatives to this EXISTING messaging ad set instead of building a campaign, so the ad set keeps its learning phase. It then owns budget, targeting and schedule, so `budgetAmount`, `budgetType`, `endDate`, `objective`, `countries`, `interests` and `audienceId` are rejected with a 400 alongside it. Its `destination_type` must match the ad's destination. budgetAmount: type: number exclusiveMinimum: 0 description: | Budget amount in the ad account's currency major units (e.g. dollars for USD, not cents). Must be > 0. Required unless `adSetId` is set, where the ad set owns it. budgetType: type: string enum: [daily, lifetime] description: Required unless `adSetId` is set. currency: type: string minLength: 3 maxLength: 3 description: | ISO 4217 currency code matching the ad account's currency (e.g. `USD`). Optional; Meta infers from the ad account when omitted. endDate: type: string format: date-time description: | ISO 8601 datetime. Required when `budgetType` is `lifetime`. countries: type: array items: { type: string, minLength: 2, maxLength: 2 } description: | ISO 3166-1 alpha-2 country codes. Defaults to `["US"]` only when no other geo (`cities`, `regions`, `zips`, `metros`, `customLocations`) is supplied. cities: type: array description: | City-level geo targeting for local CTWA campaigns. Each entry maps to Meta's TargetingGeoLocationCity. `key` is Meta's city ID. `radius` and `distance_unit` are coupled: set both or neither. Meta enforces a minimum city radius (~17 km / 10 mi); smaller values resolve to a 0-size audience and the ad fails at launch. For a tighter catchment use customLocations (lat/lng). items: type: object required: [key] properties: key: { type: string, minLength: 1 } radius: { type: number, exclusiveMinimum: 0 } distance_unit: { type: string, enum: [mile, kilometer] } regions: type: array description: | Region / state-level geo targeting. `key` is Meta's region ID (lookupable via GET /v1/ads/targeting/search?type=region). items: type: object required: [key] properties: key: { type: string, minLength: 1 } zips: type: array description: | ZIP / postal-code geo targeting. `key` is the platform's postal id resolved via /v1/ads/targeting/search. items: type: object required: [key] properties: key: { type: string, minLength: 1 } name: { type: string } metros: type: array description: | DMA / metro-area geo targeting. `key` is Meta's metro id (e.g. `DMA:807`). items: type: object required: [key] properties: key: { type: string, minLength: 1 } name: { type: string } customLocations: type: array description: | Point-radius geo (Meta `geo_locations.custom_locations`). Use for targeting a radius around a specific lat/long when no Meta city/region key fits. `distanceUnit` is required. items: type: object required: [latitude, longitude, radius, distanceUnit] properties: latitude: { type: number, minimum: -90, maximum: 90 } longitude: { type: number, minimum: -180, maximum: 180 } radius: { type: number, exclusiveMinimum: 0 } distanceUnit: { type: string, enum: [mile, kilometer] } name: { type: string } address: { type: string } ageMin: { type: integer, minimum: 13, maximum: 65 } ageMax: { type: integer, minimum: 13, maximum: 65 } interests: type: array items: type: object required: [id] properties: id: { type: string } name: { type: string } audienceId: type: string description: Custom audience ID to target. placements: type: object description: | Manual ad placements on the shared ad set. Omit for automatic placements. When set, restricts delivery to the chosen surfaces, mapped onto the ad set's `targeting.{publisher_platforms, facebook_positions, instagram_positions, messenger_positions, audience_network_positions, threads_positions, whatsapp_positions, device_platforms}`. Enum membership is validated here; Meta additionally enforces co-selection rules and restricts which placements are eligible for click-to-WhatsApp ads, returning an actionable error which we surface. properties: publisherPlatforms: type: array items: { type: string, enum: [facebook, instagram, threads, messenger, audience_network, whatsapp] } description: "Top-level platforms to deliver on. A position field below is only honoured when its parent platform is included here." facebookPositions: type: array items: { type: string, enum: [feed, right_hand_column, marketplace, video_feeds, story, search, instream_video, facebook_reels, facebook_reels_overlay, profile_feed, notification] } instagramPositions: type: array items: { type: string, enum: [stream, story, explore, explore_home, reels, profile_feed, ig_search, profile_reels] } messengerPositions: type: array items: { type: string, enum: [messenger_home, sponsored_messages, story] } audienceNetworkPositions: type: array items: { type: string, enum: [classic, rewarded_video] } threadsPositions: type: array items: { type: string, enum: [threads_stream] } whatsappPositions: type: array items: { type: string, enum: [status] } devicePlatforms: type: array items: { type: string, enum: [mobile, desktop] } description: "Restrict by device. Omit to deliver on both mobile and desktop." advantageAudience: type: integer enum: [0, 1] description: | Meta's Advantage+ audience expansion. `0` (default) keeps targeting strict; `1` lets Meta expand beyond the supplied targeting when its delivery system finds better matches. Always sent on CREATE (Meta requires it). objective: type: string enum: [OUTCOME_ENGAGEMENT, OUTCOME_SALES, OUTCOME_LEADS] description: | Defaults to `OUTCOME_ENGAGEMENT`. `OUTCOME_SALES` and `OUTCOME_LEADS` require additional account configuration (Dataset linked to the WABA for sales) and may be rejected by Meta if missing. bidStrategy: type: string enum: - LOWEST_COST_WITHOUT_CAP - LOWEST_COST_WITH_BID_CAP - COST_CAP - LOWEST_COST_WITH_MIN_ROAS description: | Meta bid strategy applied to the shared ad set. Defaults to `LOWEST_COST_WITHOUT_CAP` (auto-bid) when omitted. `LOWEST_COST_WITH_BID_CAP` and `COST_CAP` require `bidAmount`. `LOWEST_COST_WITH_MIN_ROAS` requires `roasAverageFloor`. CTWA's `optimization_goal` is fixed to `CONVERSATIONS`, but the bid strategy is independent. bidAmount: type: number exclusiveMinimum: 0 description: | Whole currency units (e.g. `5` = $5.00 on a USD account). Required when `bidStrategy` is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`; rejected otherwise. roasAverageFloor: type: number exclusiveMinimum: 0 description: | Decimal ROAS multiplier (e.g. `2.0` = 2.0× ROAS floor). Required when `bidStrategy` is `LOWEST_COST_WITH_MIN_ROAS`; rejected otherwise. Meta enforces its own upper bound server-side. dsaBeneficiary: type: string maxLength: 100 description: | Legal entity that benefits from the ad. Required when targeting EU users (EU DSA, Article 26). Optional if the ad account has a default beneficiary: set it once via `PATCH /v1/ads/accounts` or in Meta Ads Manager, and Meta fills it in whenever the field is omitted. dsaPayor: type: string maxLength: 100 description: | Legal entity that pays for the ad. Can differ from `dsaBeneficiary` (for example, an agency paying for a client's ads). Same rules as `dsaBeneficiary`: required for EU targeting unless the ad account has a default payor. WorkflowNode: type: object required: [id, type] description: A node in a workflow graph. `config` shape depends on `type`. properties: id: { type: string, description: Stable node id referenced by edges } type: type: string description: > Node kind. The 16 supported types break into four groups: messaging (send_message), control flow (trigger, condition, delay, wait_for_reply, a_b_split, end), data ops (set_variable, set_field, add_tag, remove_tag, enroll_sequence), integrations (webhook, ai, handoff, start_call). enum: - trigger - send_message - wait_for_reply - condition - set_variable - delay - webhook - ai - handoff - start_call - a_b_split - set_field - enroll_sequence - add_tag - remove_tag - end config: type: object additionalProperties: true description: > Type-specific settings. All string fields support `{{variable}}` interpolation against the run's variable bag (resolved at execution time). **trigger**: `{ triggerType: inbound_message|api_call|whatsapp_event, keywords:[string], matchType: any|contains|exact|regex, onlyFirstMessage:boolean, eventType: message_sent|message_delivered|message_read|message_failed|reaction }`. Default `triggerType` is `inbound_message` for legacy nodes. `eventType` is only honored when `triggerType` is `whatsapp_event` (WhatsApp-only). **send_message**: `{ messageType: text|template|media|interactive, text, template:{name,language,variableMapping}, media:{mediaType:image|video|audio|document, url,caption}, interactive }`. `template` and `interactive` are WhatsApp-only. `interactive.type` is inferred from the payload shape when omitted; payloads with neither `type` nor an inferable shape are rejected. **wait_for_reply**: `{ timeoutMinutes:int (max 43200), saveAs:string }`. Resume via the `'reply'` edge on inbound, or `'timeout'` edge after `timeoutMinutes` of silence. **condition**: `{ rules:[{ id, variable, operator: equals|not_equals|contains|not_contains|starts_with|ends_with|exists|not_exists|matches, value }] }`. First matching rule takes its `id` as the sourceHandle; otherwise `'default'`. **set_variable**: `{ assignments:[{ name, value }] }`. Run-scoped (lives only for this execution; use `set_field` for persistent values). **delay**: `{ delayMinutes:int (max 43200) }`. Suspends the run, resumes via timer. **webhook**: `{ url, method: GET|POST|PUT|PATCH|DELETE, headers, bodyTemplate, saveAs }`. SSRF-guarded (private/loopback/metadata IPs rejected). Response saved as `{ status, ok, body }` to `vars[saveAs]`. Edge: `'success'` on 2xx, `'error'` otherwise. **ai**: `{ provider: anthropic|openai|google|mistral|groq|openrouter, model, preset: smart|tools|cheap, systemPrompt, userPromptTemplate, saveAs, temperature, maxTokens, outputType: text|json, tools:[{ name, description, parameters }] }`. Set `provider` + `model` for BYOK (uses your stored API key); omit `provider` for the legacy Telnyx path. Edges: `'success'`, `'tool:'` (model picked a tool), `'error'`. **handoff**: `{ note, assignTo }`. Terminates the run as `exited`, flags the conversation for a human operator. **start_call**: `{ to, forwardTo, requirePermissionFirst, recordingEnabled, saveAs }`. WhatsApp-only. `forwardTo` can be `tel:+E164`, `sip:user@host`, or `wss://…` (AI voice agent). Edges: `'success'`, `'permission_required'`, `'failed'`. **a_b_split**: `{ percentage: number 0-100 (default 50) }`. Random branch picker. Edges: `'a'` (with probability `percentage/100`), `'b'`. **set_field**: `{ field, value }`. Persistent custom field on the Contact (vs `set_variable` which is run-scoped). Field name is sanitized to `[A-Za-z0-9_]`. No-op on `api_call` runs (no contact). **enroll_sequence**: `{ sequenceId, saveAs }`. Enrolls the run's contact into a Sequence. Edges: `'success'`, `'error'`. **add_tag** / **remove_tag**: `{ tag }`. Push or pull a tag on the Contact. No-op on `api_call` runs. **end**: no config. Terminates the run as `completed`. position: type: object description: Canvas coordinates (ignored by the executor; used by the visual builder). properties: x: { type: number } y: { type: number } WorkflowEdge: type: object required: [id, source, target] description: A directed edge between two nodes. properties: id: { type: string } source: { type: string, description: Source node id } target: { type: string, description: Target node id } sourceHandle: type: [string, "null"] description: > Selects a branch output of a multi-output node. Null (or omitted) = the node's single/default output. Known handles per node type: - **condition** — a rule's `id`, or `'default'` (no rule matched) - **wait_for_reply** — `'reply'` (contact replied) | `'timeout'` (no reply in window) - **webhook** — `'success'` (2xx) | `'error'` (non-2xx / fetch failed) - **ai** — `'success'` (text/JSON response) | `'tool:'` (model invoked that tool) | `'error'` (upstream failure / non-JSON in JSON mode) - **start_call** — `'success'` | `'permission_required'` | `'failed'` - **a_b_split** — `'a'` | `'b'` - **enroll_sequence** — `'success'` | `'error'` WorkflowExecutionEvent: type: object description: > One entry in a workflow execution's timeline. Emitted by the executor on every node visit and lifecycle transition, surfaced by `GET /v1/workflows/{workflowId}/executions/ {executionId}/events` for run inspection in the Runs UI. properties: action: type: string enum: - execution_started - execution_completed - execution_exited - execution_paused - execution_resumed - node_started - node_completed - node_failed - node_skipped status: { type: [string, "null"], enum: [success, failed, pending] } nodeId: { type: [string, "null"], description: Present on `node_*` events } nodeType: { type: [string, "null"], description: Present on `node_*` events } sourceHandle: type: [string, "null"] description: The edge handle the executor followed out of this node (see `WorkflowEdge.sourceHandle`) durationMs: { type: [integer, "null"], description: Node run time; present on `node_completed` and `node_failed` } errorMessage: { type: [string, "null"], description: Failure detail; present on `node_failed` and `execution_exited` } meta: type: [object, "null"] additionalProperties: true description: > Per-node-type payload. Shape varies — see WorkflowNode `type`. Examples: `send_message` → `{ messageType, text, recipient }`, `webhook` → `{ url, method, statusCode, responseTimeMs, responsePreview }`, `ai` → `{ model, provider, inputTokens, outputTokens, responsePreview }`, `condition` → `{ matchedHandle, rulesEvaluated }`, `a_b_split` → `{ percentage, chosen }`. at: { type: string, format: date-time, description: Event timestamp (UTC) } BulkUploadResult: type: object description: | Result of a CSV bulk upload. The same shape is returned for `200` (all rows succeeded or all failed) and `207` (mixed). Per-row outcomes live in `results`; the row's success is `ok`, and failures carry machine-readable codes in `errors`. properties: total: { type: integer, description: "Number of data rows processed from the CSV" } valid: { type: integer, description: "Count of rows that succeeded (results[].ok === true)" } invalid: { type: integer, description: "Count of rows that failed (total - valid)" } results: type: array description: One entry per CSV data row, in row order. items: type: object properties: rowIndex: { type: integer, description: "1-based index of the CSV data row (header excluded)" } ok: { type: boolean, description: Whether the row was created successfully } createdPostId: type: string description: ID of the created post. Present only when `ok` is true and not a dry run. errors: type: array description: | Machine-readable failure codes for this row. Present only when `ok` is false. Examples: `unknown_profile:`, `no_account_for_platform:`, `schedule_time_missing`, `rate_limited::@:`. items: { type: string } warnings: type: array description: "Top-level advisory warnings (e.g. `rows_exceed_advisory_limit:500`). Empty when none." items: { type: string } rateLimitedAccounts: type: array description: | Present only when one or more rows targeted an account currently in cooldown. Lets callers map `rate_limited:*` row errors back to structured metadata without parsing the error strings. items: type: object properties: accountId: { type: string } platform: { type: string } username: { type: string } rateLimitedUntil: { type: string, format: date-time } RedditPost: type: object description: A normalized Reddit post returned by the feed and search endpoints properties: id: { type: string, description: Reddit post ID (without type prefix) } fullname: { type: string, description: "Reddit fullname (e.g. t3_abc123)" } title: { type: string } author: { type: string } subreddit: { type: string } url: { type: string, description: "Post URL (may be a gallery URL, external link, or self-post URL)" } permalink: { type: string, description: Full permalink to the Reddit post } selftext: { type: string, description: Self-post body text (empty string for link posts) } createdUtc: { type: number, description: Unix timestamp of post creation } score: { type: integer } numComments: { type: integer } over18: { type: boolean, description: Whether the post is marked NSFW } stickied: { type: boolean } flairText: { type: [string, "null"], description: Link flair text if set } isGallery: { type: boolean, description: Whether the post is a gallery with multiple images } galleryImages: type: array description: Individual image URLs for gallery posts (only present when isGallery is true) items: { type: string, format: uri } ExternalPostSummary: type: object description: | A post synced from a platform (published directly on the platform, not through Zernio). Returned by GET /v1/posts?source=external and POST /v1/posts/sync-external. Analytics are exposed separately via GET /v1/analytics?source=external. properties: platform: type: string description: Platform the post belongs to (e.g. instagram, youtube, tiktok) platformPostId: type: string description: The platform's own post/media/video id platformPostUrl: type: string description: Canonical URL (permalink) of the post on the platform content: type: string description: Post caption / text publishedAt: type: string format: date-time description: When the post was published on the platform mediaType: type: string description: Media type (e.g. image, video, carousel) mediaUrl: type: string description: Primary media URL thumbnailUrl: type: string description: Thumbnail URL mediaItems: type: array description: Per-item media (for carousels / multi-media posts) items: type: object analytics: type: object description: | Engagement + insights for the post. `likes` and `comments` are available immediately after an on-demand sync (they come from the platform listing). `reach`, `impressions`, `views` depend on the platform's insights, which carry their own delay (e.g. ~24h on Instagram) and read 0 until the platform makes them available. properties: likes: { type: integer } comments: { type: integer } shares: { type: integer } saves: { type: integer } sends: { type: integer } clicks: { type: integer } views: { type: integer } reach: { type: integer } impressions: { type: integer } engagementRate: { type: number } lastUpdated: { type: string, format: date-time, description: When these metrics were last refreshed } ErrorResponse: type: object description: | Canonical error envelope. `error` is the human-readable message; `type`, `code`, `param`, `platform`, and `platformError` are top-level siblings for programmatic handling. For upstream platform failures (`type: platform_error`), `platformError` carries the provider's raw payload verbatim (for Meta: `error_subcode`, `error_user_title`, `error_user_msg`). properties: error: type: string description: Human-readable error message. type: type: string enum: [invalid_request_error, authentication_error, permission_error, not_found, rate_limit_error, platform_error, api_error] description: Error class for programmatic handling. code: type: string description: Stable machine-readable error code. param: type: string description: The request field that caused the error, when applicable. platform: type: string description: "Upstream platform (e.g. meta, google, tiktok) — present when type is platform_error." platformError: type: object additionalProperties: true description: | Raw error payload from the upstream platform, passed through verbatim so integrators can read provider-specific codes. For Meta this includes error_subcode, error_user_title, and error_user_msg. details: type: object additionalProperties: true description: Additional structured context (e.g. field-level validation errors). CommentAutomationAudience: type: object description: | Who a comment automation answers. Instagram only - Meta exposes the follow relationship on no other platform, and only for people who have MESSAGED the account (a comment grants no consent). `whenUnknown` is therefore the important setting: it decides what happens for a first-time commenter. properties: followerStatus: type: string enum: [any, follower, non_follower] default: any minFollowerCount: type: integer minimum: 0 description: 'Skip commenters with fewer followers than this. Omit for no size rule.' whenUnknown: type: string enum: [send, skip, verify] default: send description: | What to do when Instagram will not reveal the follow relationship. * `send` (default) - deliver the DM anyway (fails open). * `skip` - stay silent. * `verify` - send `followGate.message` with a confirm button. Tapping it is a message, which grants consent, so the re-check on the tap resolves and the real DM (or `followGate.notFollowingMessage`) follows automatically. CommentAutomationFollowGate: type: object description: 'Copy for the follow gate. Sensible defaults are used for any field left empty.' properties: message: type: string maxLength: 640 description: 'Confirmation DM sent when whenUnknown=verify.' buttonLabel: type: string maxLength: 20 description: 'Confirm button label. Defaults to "I''m following".' notFollowingMessage: type: string maxLength: 1000 description: 'Sent to a commenter we know does not follow (followerStatus=follower). Omit to stay silent on a keyword comment; a confirm tap always gets an answer.' DmButton: type: object description: | A single inline button rendered inside an auto-DM via Meta's button_template. Up to 3 buttons per automation. `url` and `postback` work on Instagram and Facebook; `phone` is Facebook-only. When buttons are set, `dmMessage` becomes the button_template text and must be 640 characters or less. required: [type, title] properties: type: { type: string, enum: [url, postback, phone] } title: { type: string, maxLength: 20, description: Button label (20 chars max) } url: { type: string, format: uri, description: Target URL (required when type is url) } payload: { type: string, description: Postback payload delivered via the messaging_postbacks webhook (required when type is postback) } phone: { type: string, description: "Phone number, e.g. +14155551234 (required when type is phone; Facebook only)" } CommentAutomationTemplate: type: object description: | A Meta generic template (product card) sent as the automation's first DM. It REPLACES the plain `dmMessage` bubble: a Meta message carries one body shape, and a comment gets exactly one private reply, so the card and the text cannot both be delivered. Put your selling copy in `subtitle`. Mutually exclusive with `buttons` (sending both is a 400). Works on both the `comment` and `story_reply` triggers. Up to 10 elements, rendered as a horizontally swipeable carousel. Rendering confirmed on the Instagram and Messenger mobile apps. required: [type, elements] properties: type: { type: string, enum: [generic] } elements: type: array minItems: 1 maxItems: 10 items: { $ref: '#/components/schemas/CommentAutomationTemplateElement' } CommentAutomationTemplateElement: type: object required: [title] properties: title: { type: string, maxLength: 80, description: 'Card headline (80 chars max). Also used as the Inbox preview for the sent DM.' } subtitle: { type: string, maxLength: 80, description: 'Card description, e.g. the price or a short pitch (80 chars max).' } imageUrl: { type: string, format: uri, description: 'Publicly reachable http(s) image rendered large above the card.' } buttons: type: array maxItems: 3 description: 'Up to 3 card buttons. A generic template has NO phone button, on either platform. `url` buttons are click-tracked when linkTracking is on.' items: type: object required: [type, title] properties: type: { type: string, enum: [url, postback] } title: { type: string, maxLength: 20 } url: { type: string, format: uri, description: 'Target URL (required when type is url)' } payload: { type: string, description: 'Postback payload delivered via the messaging_postbacks webhook (required when type is postback)' } WhatsAppTemplateButton: type: object required: [type] properties: type: type: string enum: [quick_reply, url, phone_number, otp, copy_code, flow, mpm, catalog] text: type: string description: 'Visible button label. Required for all types except copy_code (whose label is fixed by WhatsApp) and otp (omit it and WhatsApp supplies its own label, localized to the template language; an English label on a non-English template is rejected).' url: type: string format: uri description: Required when type is URL example: description: "Example value(s). Accepts either a string or an array of strings. For URL buttons, an array of URL-suffix samples; for copy_code (marketing) buttons, the coupon code as a single string. Left untyped (string | string[]) on purpose: a typed oneOf of string-vs-array breaks several SDK code generators." phone_number: type: string description: Required when type is phone_number otp_type: type: string enum: [copy_code, one_tap, zero_tap] description: Required when type is otp autofill_text: type: string package_name: type: string signature_hash: type: string flow_id: type: string flow_name: type: string flow_json: type: string flow_action: type: string navigate_screen: type: string WhatsAppTemplateComponent: oneOf: - $ref: '#/components/schemas/WhatsAppHeaderComponent' - $ref: '#/components/schemas/WhatsAppBodyComponent' - $ref: '#/components/schemas/WhatsAppFooterComponent' - $ref: '#/components/schemas/WhatsAppButtonsComponent' - $ref: '#/components/schemas/WhatsAppCarouselComponent' - $ref: '#/components/schemas/WhatsAppLimitedTimeOfferComponent' discriminator: propertyName: type mapping: header: '#/components/schemas/WhatsAppHeaderComponent' body: '#/components/schemas/WhatsAppBodyComponent' footer: '#/components/schemas/WhatsAppFooterComponent' buttons: '#/components/schemas/WhatsAppButtonsComponent' carousel: '#/components/schemas/WhatsAppCarouselComponent' limited_time_offer: '#/components/schemas/WhatsAppLimitedTimeOfferComponent' WhatsAppHeaderComponent: type: object required: [type, format] properties: type: type: string enum: [header] format: type: string enum: [text, image, video, gif, document, location] text: type: string description: Header text (may include {{1}} variable). Used when format is TEXT. example: type: object properties: header_text: type: array items: { type: string } description: Sample values for header text variables header_text_named_params: type: array items: $ref: '#/components/schemas/WhatsAppNamedParamExample' description: 'Sample values for NAMED header variables (templates using {{customer_name}}-style tokens with parameter_format: NAMED).' header_handle: type: array minItems: 1 maxItems: 1 items: type: string format: uri description: When the header format is a media type (image, video, gif, document), provide a public URL here. Zernio will download and upload it to WhatsApp on your behalf, replacing it with the internal file handle before creating the template. WhatsAppBodyComponent: type: object required: [type, text] properties: type: type: string enum: [body] text: type: string description: Body text with optional {{n}} variables add_security_recommendation: type: boolean description: Add security recommendation text (authentication templates only) example: type: object properties: body_text: type: array items: type: array items: { type: string } description: Sample values for body variables (array of arrays) body_text_named_params: type: array items: $ref: '#/components/schemas/WhatsAppNamedParamExample' description: 'Sample values for NAMED body variables (templates using {{customer_name}}-style tokens with parameter_format: NAMED).' WhatsAppNamedParamExample: type: object required: [param_name, example] properties: param_name: type: string pattern: '^[a-z0-9_]+$' description: 'Variable name as it appears in the text, without braces (e.g. customer_name for {{customer_name}}).' example: type: string description: Sample value for this variable. WhatsAppFooterComponent: type: object required: [type] properties: type: type: string enum: [footer] text: type: string description: Static footer text code_expiration_minutes: type: integer minimum: 1 description: OTP code expiry in minutes (authentication templates only) WhatsAppButtonsComponent: type: object required: [type, buttons] properties: type: type: string enum: [buttons] buttons: type: array minItems: 1 items: $ref: '#/components/schemas/WhatsAppTemplateButton' WhatsAppCarouselComponent: type: object required: [type, cards] properties: type: type: string enum: [carousel] cards: type: array minItems: 2 maxItems: 10 description: '2-10 cards. Meta requires all cards to share the same component structure; a mismatch surfaces as a rejected_reason. MARKETING category only.' items: type: object required: [components] properties: components: type: array minItems: 1 description: 'Per-card components. Each card carries its own media header + optional body + up to 2 buttons. Footer and nested carousel are not allowed inside cards.' items: $ref: '#/components/schemas/WhatsAppCarouselCardComponent' WhatsAppCarouselCardComponent: oneOf: - $ref: '#/components/schemas/WhatsAppHeaderComponent' - $ref: '#/components/schemas/WhatsAppBodyComponent' - $ref: '#/components/schemas/WhatsAppButtonsComponent' discriminator: propertyName: type mapping: header: '#/components/schemas/WhatsAppHeaderComponent' body: '#/components/schemas/WhatsAppBodyComponent' buttons: '#/components/schemas/WhatsAppButtonsComponent' WhatsAppLimitedTimeOfferComponent: type: object required: [type, limited_time_offer] properties: type: type: string enum: [limited_time_offer] limited_time_offer: type: object required: [text] properties: text: type: string minLength: 1 maxLength: 16 description: 'Short offer label (<=16 chars). MARKETING only.' has_expiration: type: boolean description: 'Toggles the countdown timer. The actual coupon code + expiry are bound at SEND time, not here.' WhatsAppSandboxSession: type: object description: | A per-user activation session against the shared WhatsApp sandbox number. Transitions `pending → active` when the inbound webhook receives a reply from the matching phone (the reply itself proves ownership). required: [id, phoneE164, status, expiresAt] properties: id: type: string description: Session id. Use this to revoke via DELETE. phoneE164: type: string description: Digits-only E.164 form (no +, spaces, or dashes). example: "34688246216" status: type: string enum: [pending, active] description: | `pending` until the phone replies to the activation template, then `active`. Expired sessions are pruned by TTL and never appear in list responses. expiresAt: type: string format: date-time description: | UTC timestamp at which the session becomes invalid. Pending sessions get a 24h window; activated sessions get 7 days. activatedAt: type: [string, "null"] format: date-time description: When the session transitioned `pending → active`, or null. createdAt: type: [string, "null"] format: date-time FoodMenuLabel: type: object required: [displayName] properties: displayName: { type: string, description: Display name of the item/section/menu } description: { type: string, description: Optional description } languageCode: { type: string, description: "BCP-47 language code (e.g. en, es)" } Money: type: object required: [currencyCode, units] properties: currencyCode: { type: string, description: "ISO 4217 currency code (e.g. USD, EUR)" } units: { type: string, description: Whole units of the amount } nanos: { type: integer, description: Nano units (10^-9) of the amount } FoodMenuItemAttributes: type: object properties: price: { $ref: '#/components/schemas/Money' } spiciness: { type: string, enum: [SPICINESS_UNSPECIFIED, MILD, MEDIUM, HOT], description: "Spiciness level (e.g. MILD, MEDIUM, HOT)" } allergen: type: array items: { type: string } description: "Allergens (e.g. DAIRY, GLUTEN, SHELLFISH)" dietaryRestriction: type: array items: { type: string } description: "Dietary labels (e.g. VEGETARIAN, VEGAN, GLUTEN_FREE)" servesNumPeople: { type: integer, minimum: 1, description: Number of people the item serves } preparationMethods: type: array items: { type: string } description: "Preparation methods (e.g. GRILLED, FRIED)" mediaKeys: type: array items: { type: string } description: Media references for item photos FoodMenuItem: type: object required: [labels] properties: labels: type: array minItems: 1 items: { $ref: '#/components/schemas/FoodMenuLabel' } attributes: { $ref: '#/components/schemas/FoodMenuItemAttributes' } options: type: array items: type: object required: [labels, attributes] properties: labels: type: array minItems: 1 items: { $ref: '#/components/schemas/FoodMenuLabel' } attributes: { $ref: '#/components/schemas/FoodMenuItemAttributes' } description: Item variants/options (e.g. sizes, preparations) FoodMenuSection: type: object required: [labels] properties: labels: type: array minItems: 1 items: { $ref: '#/components/schemas/FoodMenuLabel' } items: type: array items: { $ref: '#/components/schemas/FoodMenuItem' } FoodMenu: type: object required: [labels] properties: labels: type: array minItems: 1 items: { $ref: '#/components/schemas/FoodMenuLabel' } sections: type: array items: { $ref: '#/components/schemas/FoodMenuSection' } cuisines: type: array items: { type: string } description: "Cuisine types (e.g. AMERICAN, ITALIAN, JAPANESE)" sourceUrl: type: string format: uri description: URL of the original menu source YouTubeDailyViewsResponse: type: object properties: success: type: boolean example: true videoId: type: string description: The YouTube video ID durationSeconds: type: [integer, "null"] description: Video length in seconds (from YouTube contentDetails.duration) dateRange: type: object properties: startDate: type: string format: date endDate: type: string format: date provisionalSince: type: string format: date description: 'Present only when the range reaches into YouTube''s ~3-day processing window: the first date whose numbers are provisional and may still be revised by YouTube.' totalViews: type: integer description: Sum of views across all days in the range dailyViews: type: array items: type: object properties: date: type: string format: date views: type: integer estimatedMinutesWatched: type: number averageViewDuration: type: number description: Average view duration in seconds averageViewPercentage: type: number description: Average percentage of the video watched per view. Can exceed 100 on Shorts (looping rewatches), so do not clamp it client-side. subscribersGained: type: integer subscribersLost: type: integer likes: type: integer comments: type: integer shares: type: integer lastSyncedAt: type: [string, "null"] format: date-time description: When the data was last synced from YouTube scopeStatus: type: object properties: hasAnalyticsScope: type: boolean YouTubeVideoRetentionResponse: type: object properties: success: type: boolean example: true accountId: type: string description: The Zernio account ID for the YouTube account videoId: type: string description: The YouTube video ID title: type: [string, "null"] description: Video title publishedAt: type: [string, "null"] format: date-time description: When the video was published on YouTube durationSeconds: type: [integer, "null"] description: Video length in seconds (from YouTube contentDetails.duration) dateRange: type: object properties: startDate: type: string format: date endDate: type: string format: date provisionalSince: type: string format: date description: 'Present only when the range reaches into YouTube''s ~3-day processing window: the first date whose numbers are provisional and may still be revised by YouTube.' retentionCurve: type: array description: Up to 100 points covering the video timeline, aggregated over the date range. Empty for videos with very few views. items: type: object properties: elapsedVideoTimeRatio: type: number description: Position in the video as a ratio (0.01-1.0, exclusive end of each interval) audienceWatchRatio: type: number description: Absolute share of viewers watching at this point. Can exceed 1 (rewinds/looping, common on Shorts). relativeRetentionPerformance: type: number description: Retention vs videos of similar length (0 = worst, 0.5 = median, 1 = best) startedWatching: type: integer description: Viewers who started watching in this segment stoppedWatching: type: integer description: Viewers who stopped watching in this segment totalSegmentImpressions: type: integer description: Total views of this segment, including rewatches note: type: string description: Present only when the curve is empty, explaining why scopeStatus: type: object properties: hasAnalyticsScope: type: boolean YouTubeScopeMissingResponse: type: object properties: success: type: boolean example: false error: type: string example: "To access daily video analytics, please reconnect your YouTube account to grant the required permissions." code: type: string example: youtube_analytics_scope_missing scopeStatus: type: object properties: hasAnalyticsScope: type: boolean example: false requiresReauthorization: type: boolean example: true reauthorizeUrl: type: string format: uri description: URL to redirect user for reauthorization InstagramAccountInsightsResponse: type: object description: | Shared account-insights response envelope used by every platform-level analytics endpoint (/v1/analytics/{facebook|instagram|youtube|linkedin|tiktok}/*). The name is historical - the shape was first shipped for Instagram and every new platform endpoint reuses it for response-shape consistency. The platform field echoes back which platform served the response. properties: success: type: boolean example: true accountId: type: string description: The Zernio SocialAccount ID platform: type: string description: Platform that served this response. enum: [facebook, instagram, youtube, linkedin, tiktok] dateRange: type: object properties: since: type: string format: date until: type: string format: date metricType: type: string enum: [time_series, total_value] breakdown: type: string description: Breakdown dimension used (only present when breakdown was requested) metrics: type: object description: | Object keyed by metric name. For time_series: each metric has "total" (number) and "values" (array of {date, value}). For total_value: each metric has "total" (number) and optionally "breakdowns" (array of {dimension, value}). Monetary metrics additionally carry "unit" and "currency". Zernio never rescales money: "total" and every "values[].value" are the platform's raw numbers in the stated unit. Monetary metrics also keep "values" on metricType=total_value, because their "total" is the sum of the daily buckets the platform returned over the range: keep the series so you can reconcile that sum against the platform's own reporting before invoicing on it. A metric that could not be served is absent from this object and listed in "unavailableMetrics" instead, so an unavailable metric is never reported as a zero. additionalProperties: type: object properties: total: type: number description: Sum or aggregate value for the metric values: type: array description: Daily values (for time_series, and always on monetary metrics) items: type: object properties: date: type: string format: date value: type: number breakdowns: type: array description: Breakdown values (only for total_value with breakdown) items: type: object properties: dimension: type: string value: type: number unit: type: string enum: [micro_amount, unspecified] description: | Present on monetary metrics only. The scale of "total" and of every "values[].value", exactly as the platform returned them. "micro_amount": the platform returned an object shape carrying a micro amount, and the values are that integer, summed, unconverted. Zernio does not publish a divisor because Meta does not document one; divide by the scale you have verified against the Page's own Meta Business Suite export. On Facebook Page insights this is always content_monetization_earnings. "unspecified": the platform returned a bare number with no unit metadata. It is passed through as-is; the platform does not state whether it is major or minor currency units. On Facebook Page insights this is always monetization_approximate_earnings. currency: type: [string, "null"] description: | ISO 4217 currency of a monetary metric, or null when the platform omitted it. Always null on monetization_approximate_earnings, which Meta returns as a bare number with no currency; always present on content_monetization_earnings. example: "USD" unavailableMetrics: type: array description: | Requested metrics that could not be served. Present only when at least one metric is unavailable, and absent otherwise. Each listed metric is OMITTED from "metrics" rather than reported as 0, which is how an unavailable metric is distinguished from a genuine zero. The request itself still succeeds with HTTP 200. items: type: object properties: metric: type: string description: The requested metric name. reason: type: string enum: [not_enrolled, permission_missing, unsupported_metric, no_data, unreadable_value, mixed_currency, upstream_error] description: | "not_enrolled": the account is not enrolled in the program behind this metric. "permission_missing": the connected user lacks access to this metric. "unsupported_metric": the platform does not accept this metric name on the API version Zernio uses. "no_data": the platform returned no bucket for this metric over the requested range. "unreadable_value": the platform returned a value shape Zernio cannot read, so no total is reported. "mixed_currency": readable values disagree on currency or unit within the range. "upstream_error": any other platform failure. "no_data" is the common case in practice. The others are defensive: "not_enrolled" and "unsupported_metric" in particular have not been observed on live Facebook traffic, since a non-enrolled Page returns zeros rather than an error and metric names are validated before any platform call. message: type: string description: 'Platform-provided explanation when available (access tokens redacted), otherwise Zernio copy.' dataDelay: type: string example: "Data may be delayed up to 48 hours" FacebookPostEarningsResponse: type: object description: | Lifetime monetization earnings for one Facebook post. Same "unit" / "currency" contract and same unavailable-vs-zero contract as the Page-level response; there is no date range, no metricType, and no daily "values", because the single lifetime bucket IS the total. properties: success: type: boolean example: true accountId: type: string example: "64e1a2b3c4d5e6f7a8b9c0d1" postId: type: string description: 'The platform post ID that was queried, echoed back.' example: "123456789_987654321" platform: type: string example: "facebook" period: type: string enum: [lifetime] description: | Always "lifetime": the total is cumulative since publication and must not be summed across dates or across posts. metrics: type: object description: | One entry per served metric. A metric reported here with "total": 0 genuinely earned nothing (or its Page is not enrolled, which Meta reports identically). additionalProperties: type: object properties: total: type: number description: 'Lifetime earnings in "unit", exactly as Meta returned them. Never rescaled.' unit: type: string enum: [micro_amount, unspecified] description: | "micro_amount": Meta returned an object shape carrying a micro amount, and "total" is that integer, unconverted. Zernio does not publish a divisor because Meta does not document one; divide by the scale you have verified against the Page's own Meta Business Suite export. This is always content_monetization_earnings. "unspecified": Meta returned a bare number with no unit metadata, passed through as-is; Meta does not state whether it is major or minor currency units. This is always monetization_approximate_earnings. currency: type: [string, "null"] description: | ISO 4217 currency, or null when Meta omitted it. Always null on monetization_approximate_earnings; always present on content_monetization_earnings. example: "USD" unavailableMetrics: type: array description: | Requested metrics Meta could not serve. Present only when at least one metric is unavailable, and absent otherwise. Each listed metric is OMITTED from "metrics" rather than reported as 0. The request itself still succeeds with HTTP 200. items: type: object properties: metric: type: string description: The requested metric name. reason: type: string enum: [not_enrolled, permission_missing, unsupported_metric, no_data, unreadable_value, mixed_currency, upstream_error] description: | "not_enrolled": the account is not enrolled in the program behind this metric. "permission_missing": the connected user lacks access to this metric. "unsupported_metric": Meta does not accept this metric name on the API version Zernio uses. "no_data": Meta returned no bucket for this metric. "unreadable_value": Meta returned a value shape Zernio cannot read, so no total is reported. "mixed_currency": readable values disagree on currency or unit. "upstream_error": any other platform failure. "no_data" is the common case in practice; the others are defensive. message: type: string description: 'Platform-provided explanation when available (access tokens redacted), otherwise Zernio copy.' dataDelay: type: string InstagramDemographicsResponse: type: object properties: success: type: boolean example: true accountId: type: string description: The Zernio SocialAccount ID platform: type: string example: "instagram" metric: type: string enum: [follower_demographics, engaged_audience_demographics] timeframe: type: string enum: [this_week, this_month] description: The timeframe used for demographic data demographics: type: object description: Object keyed by breakdown dimension (age, city, country, gender) additionalProperties: type: array items: type: object properties: dimension: type: string description: The dimension value (e.g., "25-34", "US", "M") value: type: number description: Count of accounts in this dimension note: type: string example: "Demographics show top 45 entries per dimension. Requires 100+ followers." YouTubeDemographicsResponse: type: object properties: success: type: boolean example: true accountId: type: string description: The Zernio SocialAccount ID platform: type: string example: "youtube" videoId: type: string description: Present only when demographics are scoped to a single video title: type: [string, "null"] description: 'Video title (video mode only)' publishedAt: type: [string, "null"] format: date-time description: 'Video publish date (video mode only)' demographics: type: object description: Object keyed by breakdown dimension (age, gender, country) additionalProperties: type: array items: type: object properties: dimension: type: string description: The dimension value (e.g., "25-34", "US", "male") value: type: number description: Viewer percentage (age/gender) or view count (country) dateRange: type: object properties: startDate: type: string example: "2026-01-01" endDate: type: string example: "2026-03-31" provisionalSince: type: string format: date description: 'Present only when the range reaches into YouTube''s ~3-day processing window: the first date whose numbers are provisional and may still be revised by YouTube.' note: type: string example: "Age/gender values are viewer percentages (0-100). Country values are view counts. Data based on signed-in viewers only, with 2-3 day delay." Webhook: type: object description: Individual webhook configuration for receiving real-time notifications properties: _id: type: string description: Unique webhook identifier name: type: string description: Webhook name (for identification) maxLength: 50 url: type: string format: uri description: Webhook endpoint URL secret: type: string description: Secret key for HMAC-SHA256 signature verification. events: type: array items: type: string enum: [post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled, post.platform.published, post.platform.failed, post.platform.deleted, post.tiktok.url_resolved, post.external.created, post.external.updated, post.external.deleted, account.connected, account.disconnected, account.ads.initial_sync_completed, message.received, conversation.started, call.received, call.ended, call.failed, call.permission_request, message.sent, message.edited, message.deleted, message.delivered, message.read, message.failed, reaction.received, comment.received, review.new, review.updated, lead.received, ad.status_changed, whatsapp.template.status_updated, whatsapp.automatic_event, whatsapp.number.activated, whatsapp.number.declined, whatsapp.number.action_required, whatsapp.number.verification_required, whatsapp.number.suspended, whatsapp.number.reactivated, whatsapp.number.released, whatsapp.number.kyc_submitted, verification.approved, verification.failed] description: Events subscribed to isActive: type: boolean description: Whether webhook delivery is enabled lastFiredAt: type: string format: date-time description: Timestamp of last successful webhook delivery failureCount: type: integer description: Consecutive delivery failures (resets on success, webhook disabled at 10) customHeaders: type: object additionalProperties: type: string description: Custom headers included in webhook requests disabledResourceGroups: type: array items: type: string enum: [publishing, engagement, messages, contacts, analytics, ads, telephony, accounts, billing, webhooks] description: >- Resource groups this subscription does not receive (opt-out denylist, same vocabulary and same semantics as the field on API keys). Absent or empty means the subscription receives every event listed in `events`, which is how every subscription created before this field existed behaves. An event whose group is listed here is dropped before delivery even when it is still present in `events`, and the same check runs on every replay path (test fire, redelivery, dead-letter requeue). Editing the denylist applies to every event emitted afterwards; events already queued when the edit landed can still be delivered for up to five minutes after they were enqueued. WebhookLog: type: object description: A single webhook delivery attempt recorded by Zernio (30-day retention). properties: userId: type: string description: ID of the account owner the webhook belongs to webhookId: type: string description: ID of the webhook configuration that produced this delivery webhookName: type: string description: Name of the webhook configuration at delivery time eventId: type: string description: Stable webhook event ID (correlates to the delivered payload) event: type: string description: Event type that triggered the delivery (e.g. post.published) url: type: string format: uri description: Destination URL the webhook was delivered to status: type: string enum: [success, failed] description: Delivery outcome statusCode: type: integer description: HTTP status code returned by the destination endpoint requestPayload: type: object additionalProperties: true description: The JSON payload sent to the destination endpoint responseBody: type: string description: Response body returned by the destination endpoint errorMessage: type: string description: Error message when delivery failed attemptNumber: type: integer description: Delivery attempt number (increments on retries) responseTime: type: integer description: Time taken by the destination endpoint to respond, in milliseconds createdAt: type: string format: date-time description: Timestamp the delivery was attempted WebhookPayloadPost: type: object description: Webhook payload for post events required: [id, event, post, timestamp] properties: id: type: string description: Stable webhook event ID event: type: string enum: [post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled] post: type: object required: [id, content, status, scheduledFor, platforms] properties: id: type: string content: type: string status: type: string scheduledFor: type: string format: date-time publishedAt: type: string format: date-time platforms: type: array items: type: object required: [platform, status] properties: platform: type: string status: type: string accountId: type: string description: SocialAccount id this platform target published through. Use it to route events by connected account (e.g. separate staging vs production endpoints). A post can span multiple accounts. platformPostId: type: string publishedUrl: type: string error: type: string metadata: type: object additionalProperties: true description: The free-form `metadata` object supplied when the post was created, echoed back so you can map events onto your own records. Omitted when the post was created without it. timestamp: type: string format: date-time WebhookPayloadPostPlatform: type: object description: | Webhook payload for the per-platform terminal events `post.platform.published` and `post.platform.failed`, for `post.platform.deleted` (same shape, fired when Zernio's background sync detects that a platform target published through Zernio was later deleted on the platform; poll-driven ~hourly, not real-time), and for `post.tiktok.url_resolved` (same shape, fired when a published TikTok post's public URL is backfilled). Terminal events fire once per platform target inside a post as that platform reaches a terminal state (published or permanent failure). The `post` envelope mirrors the shape of `WebhookPayloadPost` so consumers can reuse rendering logic; the `platform` block identifies which specific platform transitioned; the `account` block identifies the connected social account behind that platform-write. required: [id, event, post, platform, account, timestamp] properties: id: type: string description: Stable webhook event ID. event: type: string enum: [post.platform.published, post.platform.failed, post.platform.deleted, post.tiktok.url_resolved] post: type: object required: [id, content, status, scheduledFor, platforms] properties: id: { type: string } content: { type: string } status: type: string description: | Post-level status AT FIRE TIME. May still be `publishing` if other platforms haven't terminated; check this field rather than assuming. scheduledFor: { type: string, format: date-time } publishedAt: { type: string, format: date-time } platforms: type: array items: type: object required: [platform, status] properties: platform: { type: string } status: { type: string } accountId: { type: string, description: 'SocialAccount id this platform target published through. On post.platform.* events see also the top-level `account` block.' } platformPostId: { type: string } publishedUrl: { type: string } error: { type: string } metadata: type: object additionalProperties: true description: The free-form `metadata` object supplied when the post was created, echoed back so you can map events onto your own records. Omitted when the post was created without it. platform: type: object description: The specific platform that just transitioned to a terminal state. required: [name, status] properties: name: type: string description: Platform name (e.g. `twitter`, `tiktok`, `instagram`). status: type: string enum: [published, failed, deleted] description: Terminal status this event fires on. Matches the event suffix. platformPostId: type: string description: 'Platform-native post id. Present on `published` and `deleted`, absent on `failed`.' publishedUrl: type: string description: 'Public URL to the platform-side post. Present on `published` (when the platform exposes one and it is not a draft) and on `deleted` (when one was recorded at publish time).' error: type: string description: Error message from the platform. Present on `failed` only. deletedAt: type: string format: date-time description: 'When the platform-side deletion was detected by Zernio sync (ISO 8601). Present only on `post.platform.deleted`.' account: type: object description: The connected social account the platform-write went through. required: [accountId, platform, username] properties: accountId: { type: string } platform: { type: string } username: { type: string } displayName: { type: string } timestamp: type: string format: date-time WebhookPayloadAccountConnected: type: object description: Webhook payload for account connected events required: [id, event, account, timestamp] properties: id: type: string description: Stable webhook event ID event: type: string enum: [account.connected] account: type: object required: [accountId, profileId, platform, username] properties: accountId: type: string description: The account's unique identifier (same as used in /v1/accounts/{accountId}) profileId: type: string description: The profile's unique identifier this account belongs to platform: type: string username: type: string displayName: type: string timestamp: type: string format: date-time WebhookPayloadAccountDisconnected: type: object description: Webhook payload for account disconnected events required: [id, event, account, timestamp] properties: id: type: string description: Stable webhook event ID event: type: string enum: [account.disconnected] account: type: object required: [accountId, profileId, platform, username, disconnectionType, reason] properties: accountId: type: string description: The account's unique identifier (same as used in /v1/accounts/{accountId}) profileId: type: string description: The profile's unique identifier this account belongs to platform: type: string username: type: string displayName: type: string disconnectionType: type: string enum: [intentional, unintentional] description: Whether the disconnection was intentional (user action) or unintentional (token expired/revoked) reason: type: string description: Human-readable reason for the disconnection timestamp: type: string format: date-time WebhookPayloadAccountAdsInitialSyncCompleted: type: object description: | Webhook payload for `account.ads.initial_sync_completed` events. Fired once per ads-enabled account when the initial discovery + 90-day ad backfill finishes (whether it succeeded fully, partially, or failed). required: [id, event, account, sync, timestamp] properties: id: type: string description: Stable webhook event ID event: type: string enum: [account.ads.initial_sync_completed] account: type: object required: [accountId, profileId, platform, username] properties: accountId: type: string description: The account's unique identifier (same as used in /v1/accounts/{accountId}) profileId: type: string description: The profile's unique identifier this account belongs to platform: type: string username: type: string displayName: type: string platformUserId: type: string description: The platform-side account/ad-account ID (e.g. Meta ad account ID). profilePicture: type: string format: uri description: URL of the account's profile picture, when available. platformAdAccountId: type: string description: | When the consumer scoped the connect call to a single ad account, this echoes that ID back so the webhook can be correlated to the originating connect request without consulting the consumer's DB. Meta uses the `act_*` shape. example: act_1330190928038136 platformAdAccountIds: type: array description: | Every ad-account ID that the connected token could see at discovery time. Useful for "we synced ads from these accounts" UX without a follow-up API call. Empty array when the token had no ad-account visibility. items: type: string example: ["act_1330190928038136", "act_98765432101234"] sync: type: object description: Summary of the initial ads sync backfill results. required: [status, totalAds, synced, failed] properties: status: type: string enum: [success, failure] description: Overall outcome of the initial sync. totalAds: type: integer description: Total number of ads discovered for backfill. synced: type: integer description: Number of ads successfully synced. failed: type: integer description: Number of ads that failed to sync. error: type: string description: | Free-form error message from the platform (typically Meta's Marketing API). Truncated to ~2KB. Present when `status` is `failure` (and sometimes on `success` when discovery saw zero ad accounts). For UX branching prefer `errorCategory`; this field is for human display and debugging. errorCode: type: string description: Platform-native error code if parsed (e.g. Meta `190`, `10`, `200`). errorSubcode: type: string description: Platform-native error subcode if parsed. errorCategory: type: string enum: [token_invalid, permission_denied, no_ad_accounts, rate_limited, discovery_failed, unknown] description: | Stable category for UX branching. New values may be added; existing ones are stable. Mapping: - `token_invalid`: access token is expired or revoked. Reconnect. - `permission_denied`: token lacks required scope, or the user has no role on the Business Manager that owns the ad account. Reconnect with full permissions, or have an admin grant access. - `no_ad_accounts`: token is valid but sees zero ad accounts. The user needs to connect a Business Manager that owns ad accounts. - `rate_limited`: platform throttled us. Sync will retry automatically. - `discovery_failed`: any other platform-side failure. Inspect `error`. - `unknown`: classifier could not categorize the failure. timestamp: type: string format: date-time WebhookPayloadComment: type: object description: Webhook payload for comment received events (Instagram, Facebook, Twitter/X, YouTube, LinkedIn, Bluesky, Reddit) required: [id, event, comment, post, account, timestamp] properties: id: type: string description: Stable webhook event ID event: type: string enum: [comment.received] comment: type: object required: [id, postId, platformPostId, platform, text, author, createdAt, isReply, parentCommentId] properties: id: type: string description: Platform comment ID postId: type: [string, "null"] description: Internal post ID (null for posts not published through Zernio) platformPostId: type: string description: Platform's post ID platform: type: string enum: [instagram, facebook, twitter, youtube, linkedin, bluesky, reddit] text: type: string description: Comment text content author: type: object required: [id] properties: id: type: string description: Author's platform ID username: type: string name: type: string picture: type: [string, "null"] instagramProfile: type: object description: | Instagram only, best-effort. Present ONLY for commenters who have messaged the account before: Meta gates the follow relationship behind messaging consent, and commenting does not grant it. Absent otherwise - treat a missing object as "unknown", never as "not a follower". To check on demand, call GET /v1/accounts/{accountId}/follow-status/{userId}. properties: isFollower: type: [boolean, "null"] description: The commenter follows this account. isFollowing: type: [boolean, "null"] description: This account follows the commenter. followerCount: type: [integer, "null"] isVerified: type: [boolean, "null"] createdAt: type: string format: date-time isReply: type: boolean description: Whether this is a reply to another comment parentCommentId: type: [string, "null"] description: Parent comment ID if this is a reply ad: type: object description: | Ad context. Present only when the comment was made on paid content. Instagram: populated from the webhook payload's value.media.ad_id and value.media.ad_title. Facebook: populated via a Graph API lookup of the parent post's promotion_status. Absent for comments on organic posts that are not currently promoted. properties: id: type: string description: Meta ad ID (Instagram only). title: type: string description: Ad creative title (Instagram only). promotionStatus: type: string description: | Facebook promotion status returned by Graph API. Common values: "active" (organic post currently boosted), "ineligible" (dark post or ad creative, not promotable because it already is an ad). attachment: type: object description: | Facebook only. Present on graphic-only comments (sticker, GIF, photo) that carry no text. URLs are ephemeral and may expire for Meta platforms (oe= expiry), so fetch promptly. Instagram comments do not support attachments. required: [type] properties: type: type: string description: 'Attachment type: sticker, animated_image_share, or photo.' imageUrl: type: string description: Rendered image/preview URL (from attachment.media.image.src). url: type: string description: 'Source URL (from attachment.url). For GIFs this is an l.facebook.com redirect.' post: type: object required: [id, platformPostId] properties: id: type: [string, "null"] description: Internal post ID (null for posts not published through Zernio) platformPostId: type: string description: Platform's post ID account: type: object required: [id, platform, username] properties: id: type: string description: Social account ID accountId: type: string description: Social account ID (same as id); canonical field for account filtering. platform: type: string username: type: string timestamp: type: string format: date-time WebhookPayloadLead: type: object description: Webhook payload for lead.received events (Meta Lead Gen / Instant Forms). required: [id, event, lead, account, timestamp] properties: id: type: string description: Stable webhook event ID event: type: string enum: [lead.received] lead: type: object required: [id, leadgenId, formId, fields, isOrganic, createdAt] properties: id: type: string description: Zernio lead ID (AdLead document ID) leadgenId: type: string description: Meta lead ID (the platform's leadgen_id) formId: type: string description: Lead Gen form ID the lead was submitted against formName: type: [string, "null"] description: Human-readable form name (best-effort; may be null) adId: type: [string, "null"] description: Meta ad ID that drove the lead (null for organic/test leads) adsetId: type: [string, "null"] campaignId: type: [string, "null"] fields: type: object additionalProperties: type: string description: > Flattened question key -> answer map. For multiple-choice questions the value is the option key (e.g. "k1"), not the display label. isOrganic: type: boolean description: True when the lead came from an organic post rather than a paid ad createdAt: type: string format: date-time description: Meta's lead creation time (ISO 8601) account: type: object required: [id, platform] properties: id: type: string description: Social account ID (the facebook account owning the Page) accountId: type: string description: Social account ID (same as id); canonical field for account filtering. platform: type: string enum: [facebook] timestamp: type: string format: date-time ReviewWebhookReview: type: object description: Review data shared by review.new and review.updated payloads. required: [id, platform, rating, text, reviewer, createdAt, hasReply] properties: id: type: string description: Platform review ID (e.g. "accounts/123/locations/456/reviews/789" for Google Business). platform: type: string enum: [googlebusiness] description: Platform the review originated on. Currently Google Business Profile only. rating: type: integer minimum: 1 maximum: 5 description: Star rating the reviewer gave. text: type: string description: Review text content. May be empty if the reviewer left only a rating. reviewer: type: object required: [id, name, profileImage] properties: id: type: [string, "null"] description: Platform reviewer ID. Null when the platform does not expose it (common on Google Business anonymous reviews). name: type: string profileImage: type: [string, "null"] createdAt: type: string format: date-time hasReply: type: boolean description: Whether the connected account has replied to this review. reply: type: object description: Present when hasReply is true. required: [text, createdAt] properties: text: type: string createdAt: type: string format: date-time WebhookPayloadReviewNew: type: object description: Webhook payload for the review.new event (new review posted on a connected account). required: [id, event, review, account, timestamp] properties: id: type: string description: Stable webhook event ID event: type: string enum: [review.new] review: $ref: '#/components/schemas/ReviewWebhookReview' account: type: object required: [id, platform, username] properties: id: type: string accountId: type: string description: Social account ID (same as id); canonical field for account filtering. platform: type: string username: type: string timestamp: type: string format: date-time WebhookPayloadReviewUpdated: type: object description: | Webhook payload for the review.updated event. Fired when the reviewer edits their text or rating, or when a reply is added (via the API or directly on the platform). Same shape as review.new. When a reply is present, review.hasReply is true and review.reply is populated. required: [id, event, review, account, timestamp] properties: id: type: string description: Stable webhook event ID event: type: string enum: [review.updated] review: $ref: '#/components/schemas/ReviewWebhookReview' account: type: object required: [id, platform, username] properties: id: type: string accountId: type: string description: Social account ID (same as id); canonical field for account filtering. platform: type: string username: type: string timestamp: type: string format: date-time ExternalPostWebhookPost: type: object description: Native (external) post data shared by all post.external.* payloads. required: [id, platform, accountId, url, content, mediaType, mediaItems, thumbnailUrl, publishedAt, source] properties: id: type: string description: Platform-native post ID (NOT a Zernio post ID). platform: type: string description: Platform the post lives on (e.g. "googlebusiness"). accountId: type: string description: Zernio social account ID the post belongs to. url: type: [string, "null"] description: Direct URL to the post on the platform, when available. content: type: string description: Post text. May be empty. mediaType: type: string description: One of image, video, gif, document, text, carousel. mediaItems: type: array items: $ref: '#/components/schemas/ExternalPostMediaItem' thumbnailUrl: type: [string, "null"] publishedAt: type: string format: date-time source: type: string enum: [external] description: Always "external" — distinguishes these from Zernio-originated post.* events. deletedAt: type: [string, "null"] format: date-time description: Detection time of deletion. Present on post.external.deleted; null/absent otherwise. WebhookPayloadExternalPost: type: object description: | Webhook payload for post.external.created / post.external.updated / post.external.deleted. Fired by Zernio's background sync when it detects a natively-authored post (e.g. a Google Business Profile localPost created in the Google UI), NOT a post published through Zernio. Poll-driven (~hourly), not real-time. On post.external.deleted, post.deletedAt is populated. required: [id, event, post, account, timestamp] properties: id: type: string description: Stable webhook event ID event: type: string enum: [post.external.created, post.external.updated, post.external.deleted] post: $ref: '#/components/schemas/ExternalPostWebhookPost' account: type: object required: [id, platform, username] properties: id: type: string accountId: type: string description: Social account ID (same as id); canonical field for account filtering. platform: type: string username: type: string timestamp: type: string format: date-time # ─── Shared sub-schemas for inbox lifecycle webhook payloads ──────────── # WebhookPayloadMessageEdited / Deleted / DeliveryStatus reference these # as $refs. They were added as top-level named schemas (rather than nested # refs into WebhookPayloadMessage.properties) because openapi-typescript # and datamodel-code-generator can't resolve nested-property refs — the # SDK regen fails with "Cannot find name 'WebhookPayloadMessage_properties_message'". InboxWebhookMessage: type: object description: The message object included in inbox webhook payloads. required: [id, conversationId, platform, platformMessageId, direction, text, attachments, sender, sentAt, isRead] properties: id: type: string description: Internal message ID conversationId: type: string description: Internal conversation ID platform: type: string enum: [instagram, facebook, telegram, whatsapp] platformMessageId: type: string description: Platform's message ID direction: type: string enum: [incoming, outgoing] text: type: [string, "null"] description: Message text content (retained on deleted messages for API consumers; Zernio dashboard UI hides this) attachments: type: array items: type: object required: [type, url] properties: type: type: string description: Attachment type (image, video, file, sticker, audio) url: type: string description: | Where to fetch the attachment. The contract depends on direction and platform: inbound WhatsApp media points at the authenticated `GET /v1/whatsapp/media/{mediaId}` and requires `Authorization: Bearer `, while outgoing media carries the URL originally supplied and Instagram / Facebook / Telegram carry direct platform CDN links that need no authentication. payload: type: object description: Additional attachment metadata sender: type: object required: [id] properties: id: type: string description: | Sender's platform identifier. For WhatsApp this is the phone number (without leading `+`) when available, otherwise the `businessScopedUserId`. For other platforms, the platform's own user ID. contactId: type: string description: | Zernio CRM Contact id for this sender, when one exists (joined via the ContactChannel mapping). Lets integrators link a message straight to a Contact without a follow-up Contacts API call. Omitted when the sender isn't a tracked contact (e.g. outgoing messages where the sender is the business, or first-touch messages before the contact is created). name: type: string username: type: string picture: type: string phoneNumber: type: [string, "null"] description: | WhatsApp only. Sender's phone number in E.164 format (with leading `+`). **Nullable during the BSUID rollout (April 2026+).** WhatsApp users who adopt a username can message businesses without exposing a phone number — this field is omitted for them. Match by `businessScopedUserId` instead. See `docs/whatsapp-bsuid-migration.md`. businessScopedUserId: type: string description: | WhatsApp only. Business-scoped user ID (BSUID) — Meta's canonical identifier for a WhatsApp user within your business. Present when Meta includes it in the inbound payload (rollout in progress since early April 2026). **Recommended primary identity anchor** going forward; fall back to `phoneNumber` only when this field is absent. parentBusinessScopedUserId: type: string description: | WhatsApp only. Parent BSUID for businesses with linked business portfolios. Omitted for standalone portfolios. whatsappUsername: type: string description: | WhatsApp only. User's WhatsApp username (e.g. `@jane`). Not a stable identifier — users can change it. Useful for display, not recommended as an identity anchor. instagramProfile: type: object description: Instagram profile data. Only present for Instagram conversations. properties: isFollower: { type: [boolean, "null"] } isFollowing: { type: [boolean, "null"] } followerCount: { type: [integer, "null"] } isVerified: { type: [boolean, "null"] } sentAt: type: string format: date-time isRead: type: boolean InboxWebhookConversation: type: object description: The conversation context included in inbox webhook payloads. required: [id, platformConversationId, status] properties: id: { type: string } platformConversationId: { type: string } participantId: { type: string } participantName: { type: string } participantUsername: { type: string } participantPicture: { type: string } status: type: string enum: [active, archived] contactId: type: string description: | Zernio CRM Contact ID for the participant, when one exists. Resolved by joining `participantId` to the ContactChannel collection. Best-effort: omitted when no channel matches or `participantId` is absent. Lets integrators join any inbox webhook back to the CRM Contact without needing to look at the sender — which matters for outgoing and delivery-status events whose sender is the business. InboxWebhookAccount: type: object description: The account context included in inbox webhook payloads. required: [id, platform, username] properties: id: type: string description: Social account ID accountId: type: string description: Social account ID (same value as id). Canonical field so consumers can filter every webhook event on one field (e.g. route staging vs production by account). id is kept for backward compatibility. profileId: type: string description: Zernio profile (workspace) ID this account belongs to. Use it to route or filter inbox webhooks by workspace. This is the profile ID only, not its name (resolve the name via the API with this ID). Optional; omitted on the shared WhatsApp sandbox account and when the account has no resolvable profile. platform: { type: string } username: { type: string } displayName: { type: string } # ──────────────────────────────────────────────────────────────────────── WebhookPayloadReaction: type: object description: 'Webhook payload for reaction received events (WhatsApp, Telegram, Slack, Instagram, Facebook Messenger)' required: [id, event, reaction, conversation, account, timestamp] properties: id: type: string description: Stable webhook event ID event: type: string enum: [reaction.received] reaction: type: object required: [emoji, action, platformMessageId, sender, reactedAt] properties: emoji: type: string description: | The emoji reacted with. May be an empty string when `action` is `removed` on WhatsApp (Meta does not report which emoji was removed). action: type: string enum: [added, removed] messageId: type: string description: Internal Zernio message ID of the reacted-to message, when resolvable from the platform ID. platformMessageId: type: string description: Platform-native ID of the reacted-to message (e.g. WhatsApp wamid). sender: type: object required: [id] description: 'Whoever added or removed the reaction. Usually the participant, but on Slack, Instagram and Facebook Messenger it is the business own platform id when the reaction was made from the native app: compare it with conversation.participantId.' properties: id: type: string contactId: type: string description: Zernio CRM Contact id for this sender, when one exists. name: type: string username: type: string picture: type: string phoneNumber: type: [string, "null"] description: WhatsApp only. Sender's phone number in E.164 format (with leading `+`), when available. reactedAt: type: string format: date-time conversation: $ref: '#/components/schemas/InboxWebhookConversation' account: $ref: '#/components/schemas/InboxWebhookAccount' timestamp: type: string format: date-time # ──────────────────────────────────────────────────────────────────────── WebhookPayloadMessage: type: object description: Webhook payload for message received events required: [id, event, message, conversation, account, timestamp] properties: id: type: string description: Stable webhook event ID event: type: string enum: [message.received] message: type: object required: [id, conversationId, platform, platformMessageId, direction, text, attachments, sender, sentAt, isRead] properties: id: type: string description: Internal message ID conversationId: type: string description: Internal conversation ID platform: type: string enum: [instagram, facebook, telegram, whatsapp] platformMessageId: type: string description: Platform's message ID direction: type: string enum: [incoming, outgoing] text: type: [string, "null"] description: Message text content attachments: type: array items: type: object required: [type, url] properties: type: type: string description: Attachment type (image, video, file, sticker, audio) url: type: string description: | Where to fetch the attachment. **The contract differs by platform.** - **WhatsApp**: points at `GET /v1/whatsapp/media/{mediaId}`, an authenticated Zernio endpoint. You MUST send `Authorization: Bearer `; fetching it without that header returns `401`. Download and store the bytes when this webhook arrives: Meta drops inbound media after a limited retention window, after which the endpoint answers `400` permanently and the media is unrecoverable. - **Instagram / Facebook / Telegram**: a direct platform CDN link that needs no authentication and expires on the platform's own schedule. payload: type: object description: Additional attachment metadata sender: type: object required: [id] properties: id: type: string description: | Sender's platform identifier. For WhatsApp this is the phone number (without leading `+`) when available, otherwise the `businessScopedUserId`. contactId: type: string description: Zernio CRM Contact id for this sender, when one exists (omitted for outgoing/business sender). name: type: string username: type: string picture: type: string phoneNumber: type: [string, "null"] description: | WhatsApp only. Sender's phone number in E.164 format (with leading `+`). **Nullable during the BSUID rollout (April 2026+).** WhatsApp users who adopt a username can message businesses without exposing a phone number — this field is omitted for them. Match by `businessScopedUserId` instead. See `docs/whatsapp-bsuid-migration.md`. businessScopedUserId: type: string description: | WhatsApp only. Business-scoped user ID (BSUID) — Meta's canonical identifier for a WhatsApp user within your business. Present when Meta includes it in the inbound payload (rollout in progress since early April 2026). **Recommended primary identity anchor** going forward; fall back to `phoneNumber` only when this field is absent. parentBusinessScopedUserId: type: string description: | WhatsApp only. Parent BSUID for businesses with linked business portfolios. Omitted for standalone portfolios. whatsappUsername: type: string description: | WhatsApp only. User's WhatsApp username (e.g. `@jane`). Not a stable identifier — users can change it. Useful for display, not recommended as an identity anchor. instagramProfile: type: object description: Instagram profile data for the sender. Only present for Instagram conversations. properties: isFollower: type: [boolean, "null"] description: Whether the sender follows your Instagram business account isFollowing: type: [boolean, "null"] description: Whether your Instagram business account follows the sender followerCount: type: [integer, "null"] description: The sender's follower count on Instagram isVerified: type: [boolean, "null"] description: Whether the sender is a verified Instagram user sentAt: type: string format: date-time isRead: type: boolean conversation: $ref: '#/components/schemas/InboxWebhookConversation' account: $ref: '#/components/schemas/InboxWebhookAccount' metadata: type: [object, "null"] description: 'Platform-specific message context (present when the message is a quick reply tap, postback button tap, inline keyboard callback, or a quote-reply to an earlier message)' properties: quotedMessageId: type: string description: | platformMessageId of the message this one is a quote-reply to. WhatsApp (`context.id`), Instagram and Facebook Messenger (`reply_to.mid`). On `message.sent` echoes (operator replied from the native app) this is the only metadata field populated. quickReplyPayload: type: string description: Payload from a quick reply tap (Facebook/Instagram Messenger). postbackPayload: type: string description: Payload from a postback button tap (Facebook/Instagram Messenger). postbackTitle: type: string description: Title of the tapped postback button (Facebook/Instagram Messenger). callbackData: type: string description: Callback data from an inline keyboard button tap (Telegram). interactiveType: type: string enum: [button_reply, list_reply, nfm_reply] description: | WhatsApp only. Which kind of interactive reply the user sent: `button_reply` (tap on an interactive button), `list_reply` (tap on a list row), or `nfm_reply` (a WhatsApp Flow submission). interactiveId: type: string description: | WhatsApp only. The `id` of the tapped button or list row, matching the `id` you supplied when the message was sent. Not set for Flow responses. buttonPayload: type: string description: | WhatsApp only. Payload attached to a tapped template button. Template buttons emit a plain `button` webhook (not an interactive reply), so `interactiveType` is empty while this field is populated. flowResponseJson: type: string description: | WhatsApp only. Raw `nfm_reply.response_json` string returned by a Flow submission. Useful if you need the exact wire payload; for typed access use `flowResponseData` instead. flowResponseData: type: object additionalProperties: true description: | WhatsApp only. Parsed Flow response JSON. Populated when `flowResponseJson` is valid JSON; otherwise omitted. Keys and value types depend on the specific Flow that was submitted. order: type: object description: | WhatsApp only. Cart submitted by the user from a commerce message (catalog, product, or product-list message). Meta's `order` object forwarded verbatim. properties: catalog_id: type: string description: Meta catalog the ordered products belong to. text: type: string description: Optional free-text note the user attached to the cart. product_items: type: array items: type: object properties: product_retailer_id: type: string description: Retailer ID (SKU) of the ordered product. quantity: type: integer description: Quantity ordered for this line item. item_price: type: number description: Unit price of the item. currency: type: string description: ISO 4217 currency code (e.g. USD). referredProduct: type: object description: | WhatsApp only. The product the user is asking about. Set when an inbound text carries Meta's `context.referred_product` (the user tapped "Message business" on a product). Forwarded verbatim. properties: catalog_id: type: string description: Meta catalog the product belongs to. product_retailer_id: type: string description: Retailer ID (SKU) of the product being asked about. contacts: type: array description: | WhatsApp only. Contact cards the user shared, forwarded verbatim from Meta. Read `contactsOrigin` before treating any number here as the sender's own. items: type: object additionalProperties: true contactsOrigin: type: string enum: [contact_request, other] description: | WhatsApp only. How the contact card was shared. `contact_request` means the user tapped a `request_contact_info` button, so the number is their own and consented. `other` means they picked a card from their address book: it may be anyone's, and must NOT be stored as the sender's identity. Omitted when Meta sends no origin. storyReply: type: object description: | Instagram only. Populated when an IG user replies to one of the account's stories (Meta `messaging_story_replies`). Mutually exclusive in practice with `isStoryMention`. required: [storyId] properties: storyId: type: string description: The Instagram story ID the user replied to. storyUrl: type: string description: | Meta CDN URL for the story media. Expires approximately 24 hours after the story posted; consumers must fetch promptly or treat 404s as expected. isStoryMention: type: boolean description: | Instagram only. True when the message was generated by an IG user mentioning the account in their own story (`story_mention` attachment type). Mutually exclusive in practice with `storyReply`. referral: type: [object, "null"] description: | Ad-click attribution forwarded verbatim from Meta. Populated only on the FIRST inbound message after the click; absent on subsequent messages of the same conversation. The populated subset identifies the source platform: - `ctwa_clid` and `source_*` fields: WhatsApp CTWA (Click-to-WhatsApp). Attribution window is 7 days from click. Forward to Meta Conversions API for Business Messaging replay. - `ad_id` and `ads_context_data`: Facebook Messenger CTM (Click-to-Message) or Instagram CTD (Click-to-Direct). Use `ad_id` to attribute the conversation to a specific ad. properties: ctwa_clid: type: string description: Meta's GCLID-equivalent click identifier. source_id: type: string source_type: type: string source_url: type: string headline: type: string body: type: string media_type: type: string image_url: type: string video_url: type: string thumbnail_url: type: string ad_id: type: string description: | Facebook Messenger CTM / Instagram CTD only. The Meta ad ID the user clicked to start the conversation. ref: type: string description: | Optional `ref` parameter passed through from the Meta ad creative. Facebook Messenger CTM / Instagram CTD only. source: type: string description: | Meta-supplied source identifier (e.g. `ADS`). Facebook Messenger CTM / Instagram CTD only. type: type: string description: | Meta-supplied referral type (e.g. `OPEN_THREAD`). Facebook Messenger CTM / Instagram CTD only. ads_context_data: type: object description: | Snapshot of the ad's public context at click time. Facebook Messenger CTM / Instagram CTD only. properties: ad_title: type: string photo_url: type: string video_url: type: string post_id: type: string product_id: type: string flow_id: type: string timestamp: type: string format: date-time WebhookPayloadMessageSent: type: object description: Webhook payload for message sent events (fired when a message is sent via the API, or from the WhatsApp Business app on Coexistence numbers) required: [id, event, message, conversation, account, timestamp] properties: id: type: string description: Stable webhook event ID event: type: string enum: [message.sent] message: type: object required: [id, conversationId, platform, platformMessageId, direction, text, attachments, sender, sentAt, isRead] properties: id: type: string description: Internal message ID conversationId: type: string description: Internal conversation ID platform: type: string enum: [instagram, facebook, telegram, whatsapp] platformMessageId: type: string description: Platform's message ID direction: type: string enum: [incoming, outgoing] text: type: [string, "null"] description: Message text content attachments: type: array items: type: object required: [type, url] properties: type: type: string description: Attachment type (image, video, file, sticker, audio) url: type: string description: | Where to fetch the attachment. For outgoing messages this is the media URL as sent, so for WhatsApp it is the URL you supplied when publishing (WhatsApp sends media by link), not a Zernio endpoint, and it needs no Zernio credentials. Contrast the inbound direction: `message.received` attachment URLs on WhatsApp point at the authenticated `GET /v1/whatsapp/media/{mediaId}`. payload: type: object description: Additional attachment metadata sender: type: object required: [id] properties: id: type: string contactId: type: string description: Zernio CRM Contact id for this sender, when one exists. name: type: string username: type: string picture: type: string sentAt: type: string format: date-time isRead: type: boolean source: type: string enum: [whatsapp_business_app, cloud_api] description: 'WhatsApp send origin. whatsapp_business_app when sent from the WhatsApp Business phone app on a Coexistence number; cloud_api when sent through Zernio (dashboard, API, or broadcasts). Absent on non-WhatsApp platforms. This is not the inbox metadata.source lineage field.' conversation: $ref: '#/components/schemas/InboxWebhookConversation' account: $ref: '#/components/schemas/InboxWebhookAccount' timestamp: type: string format: date-time InboxMessageEditAttachment: type: object description: Attachment snapshot inside an edit-history entry. properties: type: { type: string } url: { type: string } payload: { type: object } InboxMessageEditHistoryEntry: type: object description: One prior version of an edited message. required: [text, attachments, editedAt] properties: text: type: [string, "null"] attachments: type: array items: $ref: '#/components/schemas/InboxMessageEditAttachment' editedAt: type: string format: date-time WebhookPayloadMessageEdited: type: object description: | Webhook payload for message.edited events. Fires when the sender edits a previously-sent message. Supported platforms: Instagram, Facebook Messenger, Telegram. The message object reflects the LATEST state; editHistory contains every prior version in order (oldest first), so the last entry is the version immediately before the current content. required: [id, event, message, editHistory, editCount, editedAt, conversation, account, timestamp] properties: id: { type: string } event: { type: string, enum: [message.edited] } message: $ref: '#/components/schemas/InboxWebhookMessage' editHistory: type: array description: Prior versions of the message, oldest first. items: $ref: '#/components/schemas/InboxMessageEditHistoryEntry' editCount: type: integer description: Total number of edits applied to this message. editedAt: type: string format: date-time description: When the most recent edit happened. conversation: $ref: '#/components/schemas/InboxWebhookConversation' account: $ref: '#/components/schemas/InboxWebhookAccount' timestamp: { type: string, format: date-time } WebhookPayloadMessageDeleted: type: object description: | Webhook payload for message.deleted events. Fires when the sender deletes (unsends) a message. Supported platforms: Instagram (incoming unsend) and WhatsApp (when the business deletes an outgoing message via the Cloud API). The message.text and message.attachments fields retain the content that existed before the delete. The Zernio dashboard UI does not show this content, but authorized API consumers may access it for moderation, compliance, or archival use cases. required: [id, event, message, deletedAt, conversation, account, timestamp] properties: id: { type: string } event: { type: string, enum: [message.deleted] } message: $ref: '#/components/schemas/InboxWebhookMessage' deletedAt: type: string format: date-time conversation: $ref: '#/components/schemas/InboxWebhookConversation' account: $ref: '#/components/schemas/InboxWebhookAccount' timestamp: { type: string, format: date-time } WebhookPayloadMessageDeliveryStatus: type: object description: | Shared payload for message.delivered, message.read, and message.failed events. Fires when the platform reports a new delivery state for an outgoing message. Platform support: * message.delivered — WhatsApp, Facebook Messenger. * message.read — WhatsApp, Facebook Messenger, Instagram. * message.failed — WhatsApp only (other platforms don't expose per-message failure via webhook). required: [id, event, message, statusAt, conversation, account, timestamp] properties: id: { type: string } event: type: string enum: [message.delivered, message.read, message.failed] message: $ref: '#/components/schemas/InboxWebhookMessage' statusAt: type: string format: date-time description: When the platform reported this status. error: type: [object, "null"] description: Populated only on message.failed. properties: code: { type: integer } title: { type: string } message: { type: string } explanation: type: [string, "null"] description: | Plain-language translation of `code` (e.g. for 131026, that the recipient has likely opted out of marketing messages while utility templates are unaffected). Null for unmapped codes; fall back to title/message. conversation: $ref: '#/components/schemas/InboxWebhookConversation' account: $ref: '#/components/schemas/InboxWebhookAccount' timestamp: { type: string, format: date-time } WebhookPayloadConversationStarted: type: object description: | Fired once when a new conversation begins, in either direction. A conversation starts the first time an account and a contact exchange a message on any DM platform (Instagram, Messenger/Facebook, Telegram, WhatsApp, Twitter, Reddit, Bluesky, SMS). Platform-agnostic — one subscription covers every DM platform. required: [id, event, conversation, account, startedAt, timestamp] properties: id: { type: string, description: Stable webhook event ID } event: type: string enum: [conversation.started] conversation: type: object required: [id, platform, platformConversationId, participantName, status] properties: id: { type: string, description: Internal conversation ID } platform: type: string enum: [instagram, facebook, telegram, whatsapp, twitter, reddit, bluesky, sms, slack] platformConversationId: { type: string } participantId: { type: string, description: "Contact's platform identifier (IGSID, PSID, wa_id, etc.)" } participantName: { type: string } participantUsername: { type: string, description: Contact's handle when the platform exposes one } participantPicture: { type: string } status: type: string enum: [active, archived] contactId: type: string description: | Zernio CRM Contact ID for the participant, when one exists. Resolved by joining `participantId` to the ContactChannel collection (same join used by message.*, reaction.received, and call.* webhooks). Best-effort: omitted when no channel matches or `participantId` is absent. Lets integrators seed the CRM straight from `conversation.started` without waiting for the first `message.*` event. account: $ref: '#/components/schemas/InboxWebhookAccount' startedAt: type: string format: date-time description: When the conversation document was created. timestamp: { type: string, format: date-time } CallRecord: type: object description: | One call on a number you own, either channel. `channel` tells you which lane it took: `whatsapp` (WhatsApp Business Calling) or `pstn` (a regular phone call). List endpoints omit `transcript`; use `lastTranscriptSnippet` for a preview and the detail endpoint for the full transcript. properties: _id: { type: string } accountId: { type: string, description: "Owning social account. The unified /v1/calls/{id} detail + recording endpoints work for any channel; the channel-specific endpoints remain for account-scoped access." } conversationId: { type: [string, "null"], description: "Inbox conversation with the counterparty, when one exists." } contactId: { type: [string, "null"], description: "CRM Contact for the counterparty, when resolved." } channel: { type: string, enum: [whatsapp, pstn] } direction: { type: string, enum: [inbound, outbound] } from: { type: string, description: "Caller number (E.164)." } to: { type: string, description: "Callee number (E.164)." } forwardTo: { type: [string, "null"], description: "Destination the call was routed to (tel:/sip:/wss:), snapshotted at routing time." } greeting: { type: [string, "null"], description: "Outbound PSTN only. Message spoken to the callee on answer, before the bridge." } status: { type: string, enum: [ringing, answered, ended, failed] } isVoicemail: { type: boolean, description: True when an inbound call went to voicemail. } amd: { type: boolean, description: Outbound answering-machine detection was requested for this call. } answeredMachine: { type: [boolean, "null"], description: "With `amd`, whether a machine (vs a human) answered." } forwardCallerId: { type: string, enum: [business, caller], description: Caller ID presented on the forwarded leg. } recordingEnabled: { type: boolean, description: "Effective flag for THIS call (number default + per-call override, resolved at create time)." } transcriptionEnabled: { type: boolean } transcriptionLanguage: { type: string, enum: [auto, en, es] } startedAt: { type: string, format: date-time } answeredAt: { type: [string, "null"], format: date-time } endedAt: { type: [string, "null"], format: date-time } transferredAt: { type: [string, "null"], format: date-time, description: "When the call was blind-transferred (POST /v1/voice/calls/{id}/transfer)." } durationSeconds: { type: integer } endReason: { type: string, enum: [hangup, no_answer, rejected, error] } hangupCause: { type: [string, "null"], description: "Raw carrier hangup cause behind endReason (e.g. normal_clearing, not_found, time_limit) — the actual motive when endReason is a coarse bucket." } sipHangupCause: { type: [string, "null"], description: "SIP response code that ended the call, when SIP-signalled (e.g. '403', '488'). The real failure reason for SIP legs." } callErrors: type: array description: Per-call failure log (dial failed, bridge failed, recording error). items: type: object properties: code: { type: integer } message: { type: string } recordingUrl: { type: [string, "null"], description: "May be expired. Resolve a fresh playable URL via GET /v1/calls/{id}/recording (any channel)." } lastTranscriptSnippet: { type: [string, "null"], description: "Most recent transcript segment, for list previews." } transcript: type: array description: Full transcript segments (detail endpoint only; omitted from lists). items: type: object properties: text: { type: string } confidence: { type: number } at: { type: string, format: date-time } billing: type: object properties: metaMinutes: { type: number } telnyxSeconds: { type: number } transcriptionSeconds: { type: number } transcriptionCostUSD: { type: number } metaCostUSD: { type: number, description: 'WhatsApp channel only. Meta per-minute charge, billed by Meta directly to your WABA. Display only; not billed by Zernio.' } telnyxCostUSD: { type: number } recordingCostUSD: { type: number } billableCostUSD: { type: number, description: 'Amount Zernio bills you = telephony leg + recording + transcription (excludes any Meta portion).' } totalCostUSD: { type: number, description: 'Full cost incl. any Meta portion you pay directly. Display only.' } currency: { type: string } createdAt: { type: string, format: date-time } updatedAt: { type: string, format: date-time } WebhookPayloadCallReceived: type: object description: | Webhook payload for the `call.received` event. Fires for both inbound (UIC) and outbound (BIC) calls; branch on `call.direction` to tell them apart. required: [id, event, call, account, timestamp] properties: id: { type: string, description: Stable webhook event ID } event: type: string enum: [call.received] call: type: object properties: id: { type: string, description: Internal Zernio Call doc id } metaCallId: { type: [string, "null"], description: "Meta wacid.* call id when known" } accountId: { type: string } phoneNumberId: { type: string, description: "Meta phone_number_id" } direction: { type: string, enum: [inbound, outbound] } from: { type: string, description: "Consumer wa_id / E.164" } to: { type: string, description: "Business number (E.164)" } forwardTo: { type: string, description: "Destination snapshot at routing time" } contactId: { type: string } conversationId: { type: string } startedAt: { type: string, format: date-time } account: { $ref: '#/components/schemas/InboxWebhookAccount' } timestamp: { type: string, format: date-time } WebhookPayloadCallEnded: type: object description: | Webhook payload for the `call.ended` event. Fires on call hangup with the duration and a zero-markup billing breakdown. required: [id, event, call, account, timestamp] properties: id: { type: string } event: type: string enum: [call.ended] call: type: object properties: id: { type: string } metaCallId: { type: [string, "null"] } accountId: { type: string } phoneNumberId: { type: string } direction: { type: string, enum: [inbound, outbound] } from: { type: string } to: { type: string } startedAt: { type: string, format: date-time } endedAt: { type: string, format: date-time } durationSeconds: { type: integer } endReason: { type: string, enum: [hangup, no_answer, rejected, error] } recordingUrl: { type: string } recordingExpiresAt: { type: string, format: date-time } billing: type: object properties: metaCostUSD: { type: number, description: 'Meta per-minute charge. Billed by Meta DIRECTLY to your WhatsApp Business Account payment method (your separate Meta invoice). Zernio does NOT charge this. Display only.' } telnyxCostUSD: { type: number } recordingCostUSD: { type: number } billableCostUSD: { type: number, description: 'The amount Zernio bills you = Telnyx leg + recording. Excludes Meta (billed by Meta directly).' } totalCostUSD: { type: number, description: 'Full economic cost incl. the Meta portion you pay directly (Meta + Telnyx + recording). Display only, not the Zernio-billed amount.' } account: { $ref: '#/components/schemas/InboxWebhookAccount' } timestamp: { type: string, format: date-time } WebhookPayloadCallFailed: type: object description: | Webhook payload for the `call.failed` event. Fired when a call setup or in-progress call fails. required: [id, event, call, account, timestamp] properties: id: { type: string } event: type: string enum: [call.failed] call: type: object properties: id: { type: string } metaCallId: { type: [string, "null"] } accountId: { type: string } phoneNumberId: { type: string } direction: { type: string, enum: [inbound, outbound] } from: { type: string } to: { type: string } failedAt: { type: string, format: date-time } error: type: object properties: code: { type: integer } message: { type: string } account: { $ref: '#/components/schemas/InboxWebhookAccount' } timestamp: { type: string, format: date-time } WebhookPayloadCallPermissionRequest: type: object description: | Webhook payload for the `call.permission_request` event. Fires when a consumer accepts or rejects an interactive `call_permission_request` message. required: [id, event, permission, account, timestamp] properties: id: { type: string } event: type: string enum: [call.permission_request] permission: type: object properties: from: { type: string, description: "Consumer wa_id who replied" } response: { type: string, enum: [accept, reject] } isPermanent: { type: boolean } expirationTimestamp: { type: string, format: date-time, description: "Present only when temporary" } responseSource: { type: string, description: "Meta's response source, typically `user_action`" } account: { $ref: '#/components/schemas/InboxWebhookAccount' } timestamp: { type: string, format: date-time } WebhookPayloadAdStatusChanged: type: object description: | Webhook payload for the `ad.status_changed` event. Currently emitted only for Meta (`metaads`). Sourced from two Meta `ad_account` webhook fields: - `in_process_ad_objects` - the ad object finished processing and exited `IN_PROCESS`. `status.raw` carries Meta's `status_name`. - `with_issues_ad_objects` - the ad object entered `WITH_ISSUES`. `status.raw` is `WITH_ISSUES` and the `error` block is populated from Meta's `error_code` / `error_summary` / `error_message`. required: [id, event, account, adObject, status, timestamp] properties: id: type: string description: Stable webhook event ID event: type: string enum: [ad.status_changed] account: type: object description: The connected ad-platform account that owns the ad object. required: [accountId, profileId, platform, username] properties: accountId: type: string description: Internal Zernio account ID (same as used in /v1/accounts/{accountId}). profileId: type: string description: Internal Zernio profile ID this account belongs to. platform: type: string description: Ad platform identifier. Currently always `metaads`. example: metaads username: type: string description: Display username of the connected ad-platform account. displayName: type: string description: Human-readable display name of the account, when available. adObject: type: object description: The ad-platform object the status change applies to. required: [level, platformId, platformAdAccountId] properties: level: type: string enum: [CAMPAIGN, AD_SET, AD] description: Hierarchy level the status applies to. Mirrors Meta's `level`. Creative-level events are not forwarded. platformId: type: string description: | Platform-native ID of the campaign / ad set / ad. For Meta this is the bare numeric ID (e.g. `120244894077860689`). example: "120244894077860689" platformAdAccountId: type: string description: | Platform-native ad-account ID. For Meta this uses the `act_` shape. example: act_2129800524463520 status: type: object description: Status info. Branch on `status.raw` to handle each transition. required: [raw] properties: raw: type: string description: | Platform-native status string, forwarded verbatim. For Meta this is `status_name` from `in_process_ad_objects` (e.g. `ACTIVE`, `PAUSED`, `PENDING_REVIEW`, `ARCHIVED`, `DELETED`, `DISAPPROVED`), or `WITH_ISSUES` when sourced from `with_issues_ad_objects`. Not constrained by an `enum` — Meta may add new values. example: ACTIVE error: type: object description: | Optional. Present on most `WITH_ISSUES` events, carrying the platform's error diagnostics. May be absent on some `WITH_ISSUES` events (Meta does not always include diagnostics). Always absent for any other `status.raw` value. Always null-check before reading. required: [code] properties: code: type: string description: | Platform-native error code, forwarded verbatim. For Meta this is `error_code` as a string. Use as the stable discriminator — `summary` and `message` are localized. example: "2643001" summary: type: string description: | Short human-readable summary (Meta `error_summary`). Localized to the ad-account owner's Meta locale — display only, do not match on it. example: Ad Processing Error message: type: string description: | Full human-readable error message (Meta `error_message`). Localized — display only. timestamp: type: string format: date-time description: ISO-8601 timestamp the webhook was produced. WebhookPayloadWhatsAppTemplateStatusUpdated: type: object description: | Webhook payload for the `whatsapp.template.status_updated` event. Fired when Meta completes (re)review of a template attached to a connected WABA. Maps Meta's `message_template_status_update` field onto our event envelope. required: [id, event, account, template, timestamp] properties: id: type: string description: Stable webhook event ID event: type: string enum: [whatsapp.template.status_updated] account: type: object required: [accountId, profileId, platform, username] properties: accountId: { type: string } profileId: { type: string } platform: { type: string, enum: [whatsapp] } username: { type: string } displayName: { type: string } template: type: object required: [templateId, name, language, status, reason] properties: templateId: type: string description: Meta's `message_template_id`, returned as a string. name: type: string description: Meta's `message_template_name`. language: type: string description: Meta's `message_template_language` (e.g. `en_US`). status: type: string enum: [APPROVED, REJECTED, PENDING, PAUSED, DISABLED, IN_APPEAL, PENDING_DELETION] description: | New status. Forwarded verbatim from Meta's `event` field. `PENDING_DELETION` is the 24h-grace state after a delete request before the template is actually removed. reason: type: string description: | Meta's free-form reason for the transition. `"NONE"` on approval; an explanation string on rejection. timestamp: type: string format: date-time description: ISO-8601 timestamp the webhook was produced. WebhookPayloadTest: type: object description: Webhook payload for test deliveries required: [id, event, message, timestamp] properties: id: type: string description: Stable webhook event ID event: type: string enum: [webhook.test] message: type: string description: Human-readable test message timestamp: type: string format: date-time DiscordGuildMember: type: object description: A Discord guild member, returned verbatim from Discord's API. properties: user: type: object properties: id: { type: string, description: User snowflake } username: { type: string } discriminator: { type: string } avatar: { type: [string, "null"] } global_name: { type: [string, "null"], description: "User's display name (post-2023 Discord rebrand)" } nick: { type: [string, "null"], description: Guild-specific nickname } roles: { type: array, items: { type: string }, description: Snowflake IDs of roles assigned to this member } joined_at: { type: string, format: date-time } premium_since: { type: [string, "null"], format: date-time, description: When the user started boosting the server } DiscordRole: type: object description: A Discord guild role, returned verbatim from Discord's API. properties: id: { type: string, description: Role snowflake ID } name: { type: string } color: { type: integer, description: "Decimal color (0 = no color). Convert to hex via .toString(16)." } position: { type: integer, description: "Position in role hierarchy (higher = more authority)" } permissions: { type: string, description: Permissions bitfield as a stringified integer } managed: { type: boolean, description: True for integration-managed roles (bot roles) } mentionable: { type: boolean } hoist: { type: boolean, description: True if role is displayed separately in member list } GeoRestriction: type: object description: > Country-level geo-restriction (allowlist). When set, the post is only visible to users in the specified countries. Supported on Facebook (feed posts, videos, reels), X/Twitter (media-level restriction), and LinkedIn (organization pages only, min 300 targeted followers). Ignored on unsupported platforms. Stories (Facebook, Instagram) do not support geo-restriction. properties: countries: type: array minItems: 1 maxItems: 25 items: type: string pattern: '^[A-Z]{2}$' example: US description: > ISO 3166-1 alpha-2 country codes (uppercase). Only users in these countries can see the post. Maximum 25 countries per post. Example: ["US", "CA", "GB", "ES"]. example: ["US", "CA", "GB"] required: - countries MediaItem: type: object description: Media referenced in posts. URLs must be publicly reachable over HTTPS. Use POST /v1/media/presign for uploads up to 5GB. Zernio auto-compresses images and videos that exceed platform limits (videos over 200 MB may not be compressed). properties: type: type: string enum: [image, video, gif, document] url: type: string format: uri title: type: string description: Optional title for the media item. Used as the document title for LinkedIn PDF/carousel posts. If omitted, falls back to the post title, then the filename. altText: type: string description: "Accessibility alternative text for an image, applied on every platform that supports it: Instagram (feed images only, not Reels/Stories), Facebook, Threads, X/Twitter (max 1000 chars), LinkedIn, Bluesky, and Pinterest (max 500 chars). Ignored on platforms without alt-text support (TikTok, YouTube, Snapchat, Telegram, Reddit, Google Business, WhatsApp) and on video items where the platform does not accept it. Set once per image; the same value is sent to each selected platform." filename: type: string size: type: integer description: Optional file size in bytes mimeType: type: string description: Optional MIME type (e.g. image/jpeg, video/mp4) thumbnail: type: string format: uri description: 'Optional custom thumbnail/cover image URL for videos. Supported for Facebook video posts, Facebook Reels, regular video uploads, and LinkedIn video posts. Max 10MB, JPG/PNG recommended.' instagramThumbnail: type: string format: uri description: "Custom cover image URL for Instagram Reels. Can also be set via platformSpecificData.instagramThumbnail or platformSpecificData.reelCover. Resolution order: this field > platformSpecificData.instagramThumbnail > platformSpecificData.reelCover > platformSpecificData.thumbnailUrl (legacy)." tiktokProcessed: type: boolean description: Internal flag indicating the image was resized for TikTok ExternalPostMediaItem: type: object description: > A media item on a native (external/synced) post, as carried by post.external.* webhook payloads. Distinct from the richer MediaItem used for Zernio-authored posts: external items are always already-published (url required) and limited to image or video. Kept as a separate schema so the generated SDK model does not collide with MediaItem. required: [type, url] properties: type: type: string enum: [image, video] url: type: string thumbnail: type: string PlatformTarget: type: object properties: platform: type: string example: twitter description: "Supported values: twitter, threads, instagram, youtube, facebook, linkedin, pinterest, reddit, tiktok, bluesky, googlebusiness, telegram" accountId: oneOf: - type: string - $ref: '#/components/schemas/SocialAccount' customContent: type: string description: Platform-specific text override. When set, this content is used instead of the top-level post content for this platform. Useful for tailoring captions per platform (e.g. keeping tweets under 280 characters). customMedia: type: array items: $ref: '#/components/schemas/MediaItem' scheduledFor: type: string format: date-time description: Optional per-platform scheduled time override (uses post.scheduledFor when omitted) platformSpecificData: description: Platform-specific overrides and options. oneOf: - $ref: '#/components/schemas/TwitterPlatformData' - $ref: '#/components/schemas/ThreadsPlatformData' - $ref: '#/components/schemas/FacebookPlatformData' - $ref: '#/components/schemas/InstagramPlatformData' - $ref: '#/components/schemas/LinkedInPlatformData' - $ref: '#/components/schemas/PinterestPlatformData' - $ref: '#/components/schemas/YouTubePlatformData' - $ref: '#/components/schemas/GoogleBusinessPlatformData' - $ref: '#/components/schemas/TikTokPlatformData' - $ref: '#/components/schemas/TelegramPlatformData' - $ref: '#/components/schemas/SnapchatPlatformData' - $ref: '#/components/schemas/RedditPlatformData' - $ref: '#/components/schemas/BlueskyPlatformData' - $ref: '#/components/schemas/DiscordPlatformData' - $ref: '#/components/schemas/SlackPlatformData' additionalProperties: true status: type: string example: pending description: "Platform-specific status: pending, publishing, published, failed" platformPostId: type: string description: The native post ID on the platform (populated after successful publish) example: "1234567890123456789" platformPostUrl: type: string format: uri description: Public URL of the published post. Included in the response for immediate posts; for scheduled posts, fetch via GET /v1/posts/{postId} after publish time. example: "https://twitter.com/acmecorp/status/1234567890123456789" publishedAt: type: string format: date-time description: Timestamp when the post was published to this platform removedFromPlatformAt: type: [string, "null"] format: date-time description: >- Set when a post that was successfully published later disappears from the platform (deleted on-platform or taken down by the platform). status stays "published" (it reflects the publish outcome); poll this field to detect post-publish removals. Absent while the post is live, and cleared if the post reappears. Detection runs with the analytics sync, so expect up to a few hours of lag. isTrialReel: type: boolean description: >- Present and true only when this Instagram reel was launched as a Trial through Zernio (created with platformSpecificData.trialParams). Use it to segment trial reels in analytics. Note: Instagram's Graph API exposes no readable trial field, so this reflects creation-time intent only. It indicates the reel STARTED as a trial, not whether or when it graduated. trialGraduationStrategy: type: string enum: [MANUAL, SS_PERFORMANCE] description: >- Graduation strategy the trial reel was launched with. Present only when isTrialReel is true. errorMessage: type: string description: Human-readable error message when status is failed. Contains platform-specific error details explaining why the publish failed. errorCategory: type: string enum: [auth_expired, user_content, user_abuse, account_issue, platform_rejected, platform_error, system_error, unknown] description: "Error category for programmatic handling: auth_expired (token expired/revoked), user_content (wrong format/too long), user_abuse (rate limits/spam), account_issue (config problems), platform_rejected (policy violation), platform_error (5xx/maintenance), system_error (Zernio infra), unknown" errorSource: type: string enum: [user, platform, system] description: "Who caused the error: user (fix content/reconnect), platform (outage/API change), system (Zernio issue, rare)" Post: type: object properties: _id: { type: string } userId: oneOf: - type: string - $ref: '#/components/schemas/User' title: type: string description: | YouTube: title must be ≤ 100 characters. content: { type: string } mediaItems: type: array items: { $ref: '#/components/schemas/MediaItem' } platforms: type: array items: { $ref: '#/components/schemas/PlatformTarget' } scheduledFor: { type: string, format: date-time } timezone: { type: string } status: { type: string, enum: [draft, scheduled, publishing, published, failed, partial] } tags: type: array description: "YouTube constraints: each tag max 100 chars, combined max 500 chars, duplicates removed." items: { type: string } hashtags: type: array items: { type: string } mentions: type: array description: "Stored for reference only. This field does NOT automatically create @mentions when publishing. For LinkedIn @mentions, use the /v1/accounts/{accountId}/linkedin-mentions endpoint to resolve profile URLs to URNs, then embed the returned mentionFormat directly in the post content field." items: { type: string } visibility: { type: string, enum: [public, private, unlisted] } metadata: type: object additionalProperties: true recycling: $ref: '#/components/schemas/RecyclingState' recycledFromPostId: type: string description: ID of the original post if this post was created via recycling queuedFromProfile: type: string description: Profile ID if the post was scheduled via the queue queueId: type: string description: Queue ID if the post was scheduled via a specific queue createdAt: { type: string, format: date-time } updatedAt: { type: string, format: date-time } RecyclingConfig: type: object description: | Configure automatic post recycling (reposting at regular intervals). After the post is published, the system creates new scheduled copies at the specified interval until expiration conditions are met. Supports weekly or monthly intervals. Maximum 10 active recycling posts per account. YouTube and TikTok platforms are excluded from recycling. Content variations are recommended for Twitter and Pinterest to avoid duplicate flags. properties: enabled: type: boolean default: true description: Set to false to disable recycling on this post gap: type: integer minimum: 1 description: Number of interval units between each repost. Required when enabling recycling. example: 2 gapFreq: type: string enum: [week, month] default: month description: Interval unit for the gap. Defaults to 'month'. startDate: type: string format: date-time description: When to start the recycling cycle. Defaults to the post's scheduledFor date. expireCount: type: [integer, "null"] minimum: 1 description: Stop recycling after this many copies have been created. Send null on update to clear this limit. example: 5 expireDate: type: [string, "null"] format: date-time description: Stop recycling after this date, regardless of count. Send null on update to clear this limit. contentVariations: type: array items: type: string maxItems: 20 description: | Array of content variations for recycled copies. On each recycle, the next variation is used in round-robin order. Recommended for Twitter and Pinterest to avoid duplicate content flags. If omitted, the original post content is used for all recycled copies. Send an empty array [] to clear existing variations. Must have 2+ entries when setting variations. Platform-level customContent still overrides the base content per platform. RecyclingState: type: object description: Current recycling configuration and state on a post properties: enabled: type: boolean description: Whether recycling is currently active gap: type: integer description: Number of interval units between reposts gapFreq: type: string enum: [week, month] description: Interval unit (week or month) startDate: { type: string, format: date-time } expireCount: { type: integer } expireDate: { type: string, format: date-time } contentVariations: type: array items: type: string description: Content variations for recycled copies (if configured) contentVariationIndex: type: integer description: Current position in the content variations rotation (read-only) recycleCount: type: integer description: How many recycled copies have been created so far (read-only) nextRecycleAt: type: string format: date-time description: When the next recycled copy will be created (read-only) lastRecycledAt: type: string format: date-time description: When the last recycled copy was created (read-only) TwitterPlatformData: type: object properties: replyToTweetId: type: string description: ID of an existing tweet to reply to. The published tweet will appear as a reply in that tweet's thread. For threads, only the first tweet replies to the target; subsequent tweets chain normally. X only permits replying to your own posts or posts you are mentioned in; replying to an arbitrary other account's post is rejected by X. quoteTweetId: type: string description: ID (or full status URL) of an existing tweet to quote-repost. The published tweet becomes a quote tweet of the target. Mutually exclusive with media and poll. X only permits quoting your own posts or posts you are mentioned in / part of the conversation thread of; quoting an arbitrary other account's post is rejected by X. Billed at the standard create rate ($0.015), unlike pasting a tweet URL into the text which is billed at the URL rate ($0.20). For threads, applies to the first tweet only. replySettings: type: string enum: [following, mentionedUsers, subscribers, verified] description: Controls who can reply to the tweet. "following" allows only people you follow, "mentionedUsers" allows only mentioned users, "subscribers" allows only subscribers, "verified" allows only verified users. Omit for default (everyone can reply). For threads, applies to the first tweet only. Cannot be combined with replyToTweetId. threadItems: type: array description: > Complete sequence of tweets in a thread. The first item becomes the root tweet, subsequent items are chained as replies. When threadItems is provided, the top-level content field is used only for display and search purposes, it is NOT published. You must include your first tweet as threadItems[0]. items: type: object properties: content: { type: string } mediaItems: type: array items: { $ref: '#/components/schemas/MediaItem' } poll: type: object description: Create a poll with this tweet. Mutually exclusive with media attachments and threads. properties: options: type: array minItems: 2 maxItems: 4 items: type: string minLength: 1 maxLength: 25 description: Poll options (2-4 choices, max 25 characters each) duration_minutes: type: integer minimum: 5 maximum: 10080 description: Poll duration in minutes (5 min to 7 days) required: - options - duration_minutes longVideo: type: boolean default: false description: Enable long video uploads (over 140 seconds) using amplify_video media category. Requires the connected X account to have an active X Premium subscription. When true, videos are uploaded with the amplify_video category which supports longer durations (up to 10 minutes via API). When false or omitted, the standard tweet_video category is used (140 second limit). Note that not all Premium accounts have API long-video access, as X may require separate allowlisting. geoRestriction: $ref: '#/components/schemas/GeoRestriction' paidPartnership: type: boolean default: false description: When true, the post is labeled by X as a paid partnership / paid promotion. For threads, applies to the root tweet only. Field availability may depend on your X API access tier. madeWithAi: type: boolean default: false description: When true, the post is labeled by X as containing AI-generated media. Per X, this label is for AI-generated media, not AI-written text. For threads, applies to the root tweet only. sensitiveMedia: type: object description: Marks attached media with a sensitive-content warning. Applied to every media item in the post (requires media; ignored for text-only tweets). At least one flag must be true for the warning to be sent. properties: adultContent: type: boolean description: Content contains adult material. graphicViolence: type: boolean description: Content depicts graphic violence. other: type: boolean description: Content has other sensitive characteristics. description: > X (Twitter) geo-restriction applies at the media level. Media in geo-restricted tweets will be hidden for users outside the specified countries; the tweet text itself remains visible globally. Requires media to be attached (ignored for text-only tweets). ThreadsPlatformData: type: object properties: topic_tag: type: string minLength: 1 maxLength: 50 description: Topic tag for post categorization and discoverability on Threads. Must be 1-50 characters, cannot contain periods (.) or ampersands (&). Overrides auto-extraction from content hashtags when provided. threadItems: type: array description: > Complete sequence of posts in a Threads thread. The first item becomes the root post, subsequent items are chained as replies. When threadItems is provided, the top-level content field is used only for display and search purposes, it is NOT published. You must include your first post as threadItems[0]. items: type: object properties: content: { type: string } mediaItems: type: array items: { $ref: '#/components/schemas/MediaItem' } description: Up to 10 images per carousel (no videos). Videos must be H.264/AAC MP4, max 5 min. Images JPEG/PNG, max 8 MB. Use threadItems for reply chains. FacebookPlatformData: type: object properties: contentType: type: string enum: [story, reel] description: Set to 'story' for Page Stories (24h ephemeral) or 'reel' for Reels (short vertical video). Defaults to feed post if omitted. title: type: string description: Reel title (only for contentType=reel). Separate from the caption/content field. firstComment: type: string description: Optional first comment to post immediately after publishing (feed posts and reels, not stories). Skipped when facebookSettings.draft is true. pageId: type: string description: Target Facebook Page ID for multi-page posting. If omitted, uses the default page. Use GET /v1/accounts/{id}/facebook-page to list pages. geoRestriction: $ref: '#/components/schemas/GeoRestriction' facebookSettings: $ref: '#/components/schemas/FacebookSettings' description: > Feed posts support up to 10 images (no mixed video+image). Stories require single media (24h, no captions). Reels require single vertical video (9:16, 3-60s). Geo-restriction is a hard visibility restriction: users outside the specified countries cannot see the post. Not supported for stories. Draft, carousel, and colored-background text options live under facebookSettings, see FacebookSettings. FacebookSettings: type: object description: > Facebook options that must be nested under platformSpecificData.facebookSettings, or sent at the request root as facebookSettings. The remaining Facebook options sit directly on platformSpecificData, see FacebookPlatformData. properties: draft: type: boolean description: When true, creates the post as a draft in Facebook Publishing Tools instead of publishing immediately. Supported for feed posts (text, link, image, video) and reels. Not supported for stories. Drafts expire after ~30 days. default: false carouselCards: type: array minItems: 2 maxItems: 5 description: > Renders the post as a multi-link carousel (organic Page post). When set, mediaItems must be provided with the same length and all items must be images (no videos). Each cards[i] adds the click-through link and headline for the image at mediaItems[i]. Mutually exclusive with contentType=story|reel. Facebook display truncates name at ~35 chars and description at ~30 chars; longer strings are accepted but get truncated on render. items: type: object required: [link] properties: link: type: string format: uri description: Per-card click destination (required). name: type: string maxLength: 255 description: Per-card headline (optional, ~35-char display). description: type: string maxLength: 255 description: Per-card subhead (optional, ~30-char display). carouselLink: type: string format: uri description: > Optional top-level "See more" destination shown on the carousel end card. Defaults to the first card's link when omitted. Only used together with carouselCards. textFormatPresetId: type: string pattern: '^\d+$' description: > Facebook-defined preset ID that renders the post as large text on a colored background (Graph `text_format_preset_id`). Supply the raw numeric ID from Meta; we do not publish a catalog of presets and Facebook may change the available set. Pages only (ignored on personal profiles and groups) and text-only feed posts only: the request is rejected with 400 when mediaItems or carouselCards are present, when contentType is story or reel, or when content is empty. An attachment makes Facebook drop the background silently, so those are rejected up front. Length is NOT rejected: Facebook's composer stops offering a background at around 130 characters, but Meta documents no API limit, so longer content publishes and returns a warning instead. A URL detected in the content is NOT attached as a link preview while a preset is set, because a link attachment also makes Facebook drop the background. InstagramPlatformData: type: object properties: contentType: type: string enum: [story] description: Set to 'story' to publish as a Story. Default posts become Reels or feed depending on media. shareToFeed: type: boolean default: true description: For Reels only. When true (default), the Reel appears on both the Reels tab and your main profile feed. Set to false to post to the Reels tab only. collaborators: type: array items: { type: string } description: Up to 3 Instagram usernames to invite as collaborators (feed/Reels only) firstComment: type: string description: Optional first comment to add after the post is created (not applied to Stories) trialParams: type: object description: Trial Reels configuration. Trial reels are shared to non-followers first and can later be graduated to regular reels manually or automatically based on performance. Only applies to Reels. properties: graduationStrategy: type: string enum: [MANUAL, SS_PERFORMANCE] description: "MANUAL (graduate from Instagram app) or SS_PERFORMANCE (auto-graduate if performs well with non-followers)" userTags: type: array description: 'Tag Instagram users by username. The tag shape depends on the media: photos require x/y coordinates, Reels and videos take username only (coordinates are ignored), stories accept optional coordinates. For carousels, use mediaIndex to target specific slides (defaults to 0); video slides take username-only tags. Photo tags without valid coordinates are skipped.' items: type: object required: [username] properties: username: type: string description: Instagram username (@ symbol is optional and will be removed automatically) example: friend_username x: type: number minimum: 0 maximum: 1 description: 'X coordinate position from left edge (0.0 = left, 0.5 = center, 1.0 = right). Required for photos, ignored for Reels/videos, optional for stories.' example: 0.5 y: type: number minimum: 0 maximum: 1 description: 'Y coordinate position from top edge (0.0 = top, 0.5 = center, 1.0 = bottom). Required for photos, ignored for Reels/videos, optional for stories.' example: 0.5 mediaIndex: type: integer minimum: 0 description: Zero-based index of the carousel item to tag. Defaults to 0. Tags on out-of-range indices are ignored. example: 0 audioName: type: string description: Custom name for original audio in Reels. Replaces the default "Original Audio" label. Can only be set once. example: "My Podcast Intro" thumbOffset: type: integer minimum: 0 description: Millisecond offset from video start for the Reel cover frame. Ignored when instagramThumbnail or reelCover is provided. Defaults to 0. example: 5000 instagramThumbnail: type: string format: uri description: Custom cover image URL for Instagram Reels (JPG or PNG, publicly accessible). Overrides thumbOffset when provided. Also accepted as reelCover (alias). reelCover: type: string format: uri description: Alias for instagramThumbnail. If both are provided, instagramThumbnail takes priority. isAiGenerated: type: boolean default: false description: When true, the post is labeled by Instagram as containing AI-generated media. Per Meta, this self-disclosure label is for AI-generated media, not AI-written captions. Applies to feed posts, Reels, Stories, and carousels. description: Feed aspect ratio 0.8-1.91, carousels up to 10 items, stories require media (no captions). User tag coordinates 0.0-1.0 from top-left. Images over 8 MB and videos over platform limits are auto-compressed. LinkedInPlatformData: type: object properties: documentTitle: type: string description: Title displayed on LinkedIn document (PDF/carousel) posts. Required by LinkedIn for document posts. If omitted, falls back to the media item title, then the filename. organizationUrn: type: string description: Target LinkedIn Organization URN (e.g. "urn:li:organization:123456789"). If omitted, uses the default org. Use GET /v1/accounts/{id}/linkedin-organizations to list orgs. firstComment: type: string description: Optional first comment to add after the post is created disableLinkPreview: type: boolean description: Set to true to disable automatic link previews for URLs in the post content (default is false) reshareUrl: type: string description: "LinkedIn post link to repost (use the post's \"Copy link to post\" action), or a urn:li:share / urn:li:ugcPost / urn:li:groupPost URN. The published post becomes a quote-reshare: your content is shown as the commentary and the original post is embedded underneath (LinkedIn's \"repost with your thoughts\"). Mutually exclusive with media. Works on personal profiles and organization pages." geoRestriction: $ref: '#/components/schemas/GeoRestriction' description: > Up to 20 images, no multi-video. Single PDF supported (max 100MB). Link previews auto-generated when no media attached. Use organizationUrn for multi-org posting. Geo-restriction only works for organization pages (not personal profiles) and requires the targeted audience to exceed 300 followers. MoneyAmount: type: object required: [amount, currencyCode] properties: amount: { type: string, description: "Amount as a decimal string, e.g. \"88.59\"." } currencyCode: { type: string, description: "ISO 4217 currency code, e.g. \"USD\"." } LinkedInAdsPlatformData: type: object additionalProperties: false properties: costType: type: string enum: [CPM, CPC, CPV] description: | Campaign cost model (billing event). Defaults to `CPM`. Required when `unitCost` is set so the manual bid applies to an explicit cost model. unitCost: type: number description: | Manual bid in WHOLE account-currency units (e.g. 2.5 = $2.50). Requires `costType`. Omit for LinkedIn's automated (max delivery) bidding. LinkedIn enforces its own per-audience min/max bid bounds. optimizationTargetType: type: string description: | Campaign `optimizationTargetType` (e.g. `MAX_CLICK`, `TARGET_COST_PER_CLICK`, `MAX_IMPRESSION`). Forwarded verbatim, LinkedIn validates compatibility with the objective and `costType`. Omit for the objective-derived default: `awareness` gets `MAX_IMPRESSION`, `video_views` gets `MAX_VIDEO_VIEW`, and every other goal gets `MAX_CLICK`. `lead_generation` and `conversions` also get `MAX_CLICK`, because `MAX_LEAD` and `MAX_CONVERSION` need a lead gen form or a conversion rule that neither creation flow attaches. The default applies only to `SPONSORED_UPDATES` campaigns (every boost, and the image, video and carousel standalone ads), never to the `TEXT_AD`, `DYNAMIC` and `SPONSORED_INMAILS` campaigns the other creative formats produce. It is also skipped when `unitCost` or a non-`CPM` `costType` is set, since those select manual bidding and the bid is then yours to choose. creativeSelection: type: string enum: [OPTIMIZED, ROUND_ROBIN] description: How LinkedIn rotates creatives within the campaign. Defaults to `OPTIMIZED`. audienceExpansionEnabled: type: boolean description: Enable LinkedIn audience expansion. Defaults to false. offsiteDeliveryEnabled: type: boolean description: Deliver on the LinkedIn Audience Network. Defaults to false. connectedTelevisionOnly: type: boolean description: Restrict delivery to Connected TV inventory. carousel: type: object additionalProperties: false required: [cards] description: | POST /v1/ads/create only. Carousel ad with 2-10 image cards. Mutually exclusive with the other creative sources. properties: cards: type: array minItems: 2 maxItems: 10 items: type: object additionalProperties: false required: [imageUrl] properties: imageUrl: { type: string, format: uri } headline: type: string description: Card title. Falls back to the ad-level headline. landingUrl: type: string format: uri description: | Per-card click destination. LinkedIn requires one on every card; the ad-level `linkUrl` backfills cards that omit it. document: type: object additionalProperties: false required: [url, title] description: | POST /v1/ads/create only. Document ad rendered as an in-feed viewer. PDF, PPT or DOC up to 100MB. Mutually exclusive with the other creative sources. properties: url: { type: string, format: uri } title: type: string description: Document title. spotlight: type: object additionalProperties: false required: [headline, callToAction, landingUrl] description: | POST /v1/ads/create only. Dynamic Spotlight Ad personalized with the viewer's profile photo. Supported goals: traffic, awareness. logoUrl and organizationName default to the Company Page's; set them explicitly if LinkedIn rejects the create with a 404. Mutually exclusive with the other creative sources. properties: headline: { type: string } description: type: string description: Mutually exclusive with backgroundImageUrl. callToAction: type: string description: Button label text. landingUrl: { type: string, format: uri } logoUrl: { type: string, format: uri } organizationName: { type: string } showMemberProfilePhoto: { type: boolean, description: Defaults to true. } backgroundImageUrl: type: string format: uri description: Custom background. Replaces the description and the profile photo. follower: type: object additionalProperties: false required: [headline, description, callToAction] description: | POST /v1/ads/create only. Dynamic Follower Ad promoting the Company Page. Supported goals: engagement, awareness. headline and description take exactly one of preApproved or custom. Mutually exclusive with the other creative sources. properties: headline: type: object additionalProperties: false properties: preApproved: type: string description: LinkedIn preset id, not reviewed. Example GROW_YOUR_BUSINESS_INSIGHTS. custom: type: string description: Free text, reviewed by LinkedIn. description: type: object additionalProperties: false properties: preApproved: type: string description: LinkedIn preset id, not reviewed. Example GET_LATEST_JOBS_AND_INDUSTRY_NEWS. custom: type: string description: Free text, reviewed by LinkedIn. callToAction: type: string enum: [VISIT_ORGANIZATION_COMPANY_PAGE, VISIT_ORGANIZATION_LIFE_PAGE, VISIT_ORGANIZATION_JOBS_PAGE, VISIT_ORGANIZATION_CAREERS_PAGE] logoUrl: { type: string, format: uri } organizationName: { type: string } showMemberProfilePhoto: { type: boolean, description: Defaults to true. } jobs: type: object additionalProperties: false required: [headline, buttonLabel] description: | POST /v1/ads/create only. Dynamic Jobs Ad promoting your open roles, personalized with the viewer's profile photo. Requires goal job_applicants and a Company Page with active job postings. headline and buttonLabel take exactly one of preApproved or custom. logoUrl and organizationName default to the Company Page's. Mutually exclusive with the other creative sources. properties: headline: type: object additionalProperties: false properties: preApproved: type: string description: LinkedIn preset id, not reviewed. Example MEMBER_READY_FOR_YOUR_DREAM_JOB. custom: type: string description: Free text, reviewed by LinkedIn. buttonLabel: type: object additionalProperties: false properties: preApproved: type: string description: LinkedIn preset id, not reviewed. One of SEE_MORE_JOBS, VIEW_MORE, CAREERS_AT_COMPANY. custom: type: string description: Free text, reviewed by LinkedIn. logoUrl: { type: string, format: uri } organizationName: { type: string } showMemberProfilePhoto: { type: boolean, description: Defaults to true. } textAd: type: object additionalProperties: false required: [headline, description, landingUrl] description: | POST /v1/ads/create only. Classic right-rail Text Ad. The copy lives here; ad-level body and headline are not used. Mutually exclusive with the other creative sources. properties: headline: type: string maxLength: 25 description: type: string maxLength: 75 landingUrl: type: string format: uri imageUrl: type: string format: uri description: Optional 100x100 image. conversation: type: object additionalProperties: false required: [subject, firstMessageId, messages] description: | POST /v1/ads/create only. Conversation Ad: a choose-your-path message tree delivered to the member's LinkedIn inbox. Messages are flat nodes wired by local ids; each button either opens a url or leads to nextMessageId. Cycles, unknown ids and a missing firstMessageId return a 400. LinkedIn does not deliver message ads to EU members. Mutually exclusive with the other creative sources. properties: subject: type: string description: InMail subject shown in the inbox. sender: type: string description: | Person or organization URN. Defaults to the authoring Company Page. The sender must be approved for the ad account first (Campaign Manager > Manage message ad senders) or LinkedIn rejects the create with SINMAIL_SENDER_NOT_APPROVED. body: type: string description: Optional intro body (HTML allowed). footer: type: string description: Terms shown at the bottom of the message. headline: type: string description: Conversation headline. Defaults to the first message's first line. firstMessageId: { type: string } messages: type: array minItems: 1 maxItems: 25 items: type: object additionalProperties: false required: [id, text] properties: id: { type: string } text: { type: string, maxLength: 500 } buttons: type: array minItems: 1 maxItems: 5 items: type: object additionalProperties: false required: [text] properties: text: { type: string, maxLength: 35 } nextMessageId: type: string description: Continues the conversation at this message. Exactly one of nextMessageId or url. url: type: string format: uri description: Opens this landing page. Exactly one of nextMessageId or url. event: type: object additionalProperties: false required: [urn] description: | POST /v1/ads/create only. Promotes an existing LinkedIn Event; no headline needed. Mutually exclusive with the other creative sources. properties: urn: type: string pattern: '^urn:li:event:\d+$' description: LinkedIn Event URN, urn:li:event:N. thoughtLeader: type: object additionalProperties: false required: [postUrn] description: | POST /v1/ads/create only. Sponsors an existing LinkedIn post (a share or ugcPost authored by your organization's Company Page) as the creative, keeping its commentary, author and engagement. Unlike boostPost, which provisions its own CampaignGroup + Campaign around the post, this variant attaches the reference under the campaign /v1/ads/create builds — same shape as every other format, so the caller can pick bidding / targeting / schedule freely. No headline, body, imageUrl or organization are needed; the referenced post carries its own commentary and author. Mutually exclusive with the other creative sources. Posts from personal profiles (Thought Leader Ads) are NOT supported (see postUrn). properties: postUrn: type: string pattern: '^urn:li:(share|ugcPost):\d+$' description: > LinkedIn share or ugcPost URN, urn:li:share:N or urn:li:ugcPost:N. Get it via "Copy link to post" on the target LinkedIn post (the URL contains -share- for a share or -ugcPost- for a ugcPost, then the numeric id). The post must be authored by an organization (Company Page). Member (personal profile) posts, i.e. Thought Leader Ads proper, are rejected by LinkedIn's public Marketing API regardless of sponsorship approval and of post type (a LinkedIn limitation; their Campaign Manager creates those through a private API). Referencing a member post returns a 422 with a clear error. description: > LinkedIn-specific options for POST /v1/ads/boost and POST /v1/ads/create: campaign bidding and delivery controls, plus the LinkedIn-only creative formats on /v1/ads/create. Unknown keys are rejected. PinterestPlatformData: type: object properties: title: type: string maxLength: 100 description: Pin title. Defaults to first line of content or "Pin". Must be ≤ 100 characters. boardId: type: string description: Target Pinterest board ID. If omitted, the first available board is used. link: type: string format: uri description: Destination link (pin URL) coverImageUrl: type: string format: uri description: Optional cover image for video pins coverImageKeyFrameTime: type: integer description: Optional key frame time in seconds for derived video cover YouTubePlatformData: type: object properties: title: type: string maxLength: 100 description: Video title. Defaults to first line of content or "Untitled Video". Must be ≤ 100 characters. visibility: type: string enum: [public, private, unlisted] default: public description: "Video visibility: public (default, anyone can watch), unlisted (link only), private (invite only)" madeForKids: type: boolean default: false description: COPPA compliance flag. Set true for child-directed content (restricts comments, notifications, ad targeting). Defaults to false. YouTube may block views if not explicitly set. firstComment: type: string maxLength: 10000 description: Optional first comment to post immediately after video upload. Up to 10,000 characters (YouTube's comment limit). containsSyntheticMedia: type: boolean default: false description: AI-generated content disclosure. Set true if the video contains synthetic content that could be mistaken for real. YouTube may add a label. categoryId: type: string default: '22' description: "YouTube video category ID. Defaults to 22 (People & Blogs). Common: 1 (Film), 2 (Autos), 10 (Music), 15 (Pets), 17 (Sports), 20 (Gaming), 23 (Comedy), 24 (Entertainment), 25 (News), 26 (Howto), 27 (Education), 28 (Science & Tech)." playlistId: type: string description: "Optional YouTube playlist ID to add the video to after upload (e.g. 'PLxxxxxxxxxxxxx'). Use GET /v1/accounts/{id}/youtube-playlists to list available playlists. Works for both immediate and scheduled uploads. Quota cost: 50 YouTube API units per call." description: Videos under 3 min auto-detected as Shorts. Custom thumbnails for regular videos only. Scheduled videos are uploaded immediately with the specified visibility. GoogleBusinessPlatformData: type: object properties: locationId: type: string description: Target GBP location ID (e.g. "locations/123456789"). If omitted, uses the default location. Use GET /v1/accounts/{id}/gmb-locations to list locations. languageCode: type: string description: BCP 47 language code (e.g. "en", "de", "es"). Auto-detected if omitted. Set explicitly for short or mixed-language posts. example: "de" topicType: type: string enum: [STANDARD, EVENT, OFFER] default: STANDARD description: "Post type. STANDARD is a regular update. EVENT requires the event object. OFFER requires the offer object. Defaults to STANDARD if omitted." callToAction: type: object description: Optional call-to-action button displayed on the post properties: type: type: string enum: [LEARN_MORE, BOOK, ORDER, SHOP, SIGN_UP, CALL] description: "Button action type: LEARN_MORE, BOOK, ORDER, SHOP, SIGN_UP, CALL" url: type: string format: uri description: Destination URL for the CTA button (required when callToAction is provided) required: [type, url] event: type: object description: "Event details. Required when topicType is EVENT. Google returns 400 if omitted for EVENT posts." properties: title: type: string description: Event name (displayed as the event heading on Google Search and Maps) example: "Grand Opening Weekend" schedule: type: object description: "Event date/time range. Uses Google's date format (NOT ISO 8601)." properties: startDate: type: object description: "Event start date as { year, month, day }" properties: year: type: integer example: 2026 month: type: integer minimum: 1 maximum: 12 example: 5 day: type: integer minimum: 1 maximum: 31 example: 15 required: [year, month, day] startTime: type: object description: "Optional start time as { hours, minutes } in 24h format" properties: hours: type: integer minimum: 0 maximum: 23 example: 9 minutes: type: integer minimum: 0 maximum: 59 example: 0 endDate: type: object description: "Event end date as { year, month, day }" properties: year: type: integer example: 2026 month: type: integer minimum: 1 maximum: 12 example: 5 day: type: integer minimum: 1 maximum: 31 example: 16 required: [year, month, day] endTime: type: object description: "Optional end time as { hours, minutes } in 24h format" properties: hours: type: integer minimum: 0 maximum: 23 example: 17 minutes: type: integer minimum: 0 maximum: 59 example: 0 required: [startDate, endDate] required: [title, schedule] offer: type: object description: "Offer details. Required when topicType is OFFER. All fields are optional per Google's API, but at least one is recommended." properties: redeemOnlineUrl: type: string format: uri description: URL where the offer can be redeemed online termsConditions: type: string description: Terms and conditions for the offer couponCode: type: string description: Coupon code for the offer example: "SAVE20" description: "Text and single image only (no videos). Supports STANDARD, EVENT, OFFER, and ALERT post types. Posts appear on GBP, Google Search, and Maps. Use locationId for multi-location posting. Schedule dates accept both ISO 8601 strings (e.g. '2026-04-15T09:00:00Z') and Google's native {year, month, day} objects." TikTokPlatformData: type: object description: | Photo carousels up to 35 images. Video titles up to 2200 chars, photo titles truncated to 90 chars. privacyLevel must match creator_info options. Both camelCase and snake_case accepted. Creator Inbox (draft mode): Set draft: true to send content to the TikTok Creator Inbox instead of publishing immediately. The creator receives an inbox notification and completes the post using TikTok's editing flow. This maps to TikTok's post_mode: "MEDIA_UPLOAD" internally. Important: The field publish_type is NOT supported. Use draft: true for Creator Inbox flow. Photo drafts use the /v2/post/publish/content/init/ endpoint with post_mode: "MEDIA_UPLOAD". Video drafts use the dedicated /v2/post/publish/inbox/video/init/ endpoint. When draft: true, the video.upload scope is required. When draft is false or omitted (direct post), the video.publish scope is required. For Creator Inbox, TikTok app version must be 31.8 or higher. properties: draft: type: boolean description: | When true, sends the post to the TikTok Creator Inbox as a draft instead of publishing immediately. The creator receives an inbox notification to complete posting via TikTok's editing flow. Maps to TikTok API post_mode: "MEDIA_UPLOAD" (photos) or the dedicated inbox endpoint (videos). When false or omitted, publishes directly via post_mode: "DIRECT_POST". Note: publish_type is not a supported field. Use this field instead. privacyLevel: type: string description: One of the values returned by the TikTok creator info API for the account allowComment: type: boolean description: Allow comments on the post allowDuet: type: boolean description: Allow duets (required for video posts) allowStitch: type: boolean description: Allow stitches (required for video posts) commercialContentType: type: string enum: [none, brand_organic, brand_content] description: | Type of commercial content disclosure. Sufficient on its own: "brand_organic" ("Your Brand") implies isBrandOrganicPost and "brand_content" ("Branded Content", paid partnership) implies brandPartnerPromote, so you don't need to send the boolean flags separately. Branded content cannot be posted with privacyLevel SELF_ONLY. brandPartnerPromote: type: boolean description: | Whether the post promotes a brand partner (branded content / paid partnership). Only needed to disclose BOTH types at once (set it alongside commercialContentType "brand_organic"), or to override the value implied by commercialContentType. isBrandOrganicPost: type: boolean description: | Whether the post promotes the creator's own brand (brand organic). Only needed to disclose BOTH types at once (set it alongside commercialContentType "brand_content"), or to override the value implied by commercialContentType. contentPreviewConfirmed: type: boolean description: User has confirmed they previewed the content expressConsentGiven: type: boolean description: User has given express consent for posting mediaType: type: string enum: [video, photo] description: Optional override. Defaults based on provided media items. videoCoverTimestampMs: type: integer description: Optional for video posts. Timestamp in milliseconds to select which frame to use as thumbnail (defaults to 1000ms/1 second). Ignored when videoCoverImageUrl is provided. minimum: 0 videoCoverImageUrl: type: string format: uri description: Optional for video posts. URL of a custom thumbnail image (JPG, PNG, or WebP, max 20MB). The image is stitched as a single frame at the start of the video and used as the cover. Overrides videoCoverTimestampMs when provided. photoCoverIndex: type: integer description: Optional for photo carousels. Index of image to use as cover, 0-based (defaults to 0/first image). minimum: 0 autoAddMusic: type: boolean description: When true, TikTok may add recommended music (photos only) videoMadeWithAi: type: boolean description: Set true to disclose AI-generated content description: type: string maxLength: 4000 description: Optional long-form description for photo posts (max 4000 chars). Recommended when content exceeds 90 chars, as photo titles are auto-truncated. TelegramPlatformData: type: object properties: parseMode: type: string enum: [HTML, Markdown, MarkdownV2] description: Text formatting mode for the message (default is HTML) disableWebPagePreview: type: boolean description: Disable link preview generation for URLs in the message disableNotification: type: boolean description: Send the message silently (users will receive notification without sound) protectContent: type: boolean description: Protect message content from forwarding and saving description: Text, images (up to 10), videos (up to 10), and mixed media albums. Captions up to 1024 chars for media, 4096 for text-only. SnapchatPlatformData: type: object properties: contentType: type: string enum: [story, saved_story, spotlight] default: story description: "Content type: story (ephemeral 24h, default), saved_story (permanent on Public Profile), spotlight (video feed)" description: "Requires a Public Profile. Single media item only. Content types: story (ephemeral 24h), saved_story (permanent, title max 45 chars), spotlight (video, max 160 chars)." RedditPlatformData: type: object properties: subreddit: type: string description: Target subreddit name (without "r/" prefix). Overrides the default. Use GET /v1/accounts/{id}/reddit-subreddits to list options. example: socialmedia title: type: string maxLength: 300 description: Post title. Defaults to the first line of content, truncated to 300 characters. url: type: string format: uri description: URL for link posts. If provided (and forceSelf is not true), creates a link post instead of a text post. forceSelf: type: boolean description: When true, creates a text/self post even when a URL or media is provided. flairId: type: string description: Flair ID for the post. Required by some subreddits. Use GET /v1/accounts/{id}/reddit-flairs?subreddit=name to list flairs. example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" flairText: type: string description: Custom flair text, for subreddits that allow free-text flair. Ignored when flairId is provided (flairId wins). nsfw: type: boolean default: false description: Mark the post as NSFW (Not Safe For Work / over 18). spoiler: type: boolean default: false description: Mark the post as a spoiler. The subreddit must have spoiler tagging enabled for this to take effect. sendreplies: type: boolean default: true description: Whether to receive inbox replies for comments on this post. Set to false to opt out. nativeVideo: type: boolean description: > Controls Reddit's native video upload flow. When true (default for video mediaItems), the video is uploaded to Reddit's CDN and submitted with kind=video so it renders as an embedded Reddit video player. Reddit transcodes server-side (1080p/30fps cap). Set to false to fall back to a legacy link post. If the subreddit blocks video posts, the upload falls back to a link post automatically. default: true videogif: type: boolean description: When true (and nativeVideo is active), submits the video as a silent videogif (kind=videogif). Use for short looping clips without audio. videoPosterUrl: type: string format: uri description: Optional poster/thumbnail image URL for native video posts. If omitted, the first frame of the video is extracted and used automatically. description: Posts are either link (with URL/media), native video (via nativeVideo), or self (text-only). Use forceSelf to override. Subreddit defaults to the account's configured one. Some subreddits require a flair. BlueskyPlatformData: type: object properties: threadItems: type: array description: > Complete sequence of posts in a Bluesky thread. The first item becomes the root post, subsequent items are chained as replies. When threadItems is provided, the top-level content field is used only for display and search purposes, it is NOT published. You must include your first post as threadItems[0]. items: type: object properties: content: type: string mediaItems: type: array items: $ref: '#/components/schemas/MediaItem' description: | Bluesky post settings. Supports text posts with up to 4 images or a single video. threadItems creates a reply chain (Bluesky thread). Images exceeding 1MB are automatically compressed. Alt text supported via mediaItem properties. DiscordPlatformData: type: object required: [channelId] properties: channelId: type: string description: Target channel snowflake ID. Determines which channel in the connected server receives the message. example: "1234567890123456789" embeds: type: array description: Up to 10 Discord embed objects (combined max 6,000 characters across all embeds). Sent alongside or instead of plain-text content. maxItems: 10 items: type: object properties: title: type: string description: Embed title (max 256 chars) description: type: string description: Embed body text (max 4,096 chars) url: type: string description: URL the title links to color: type: integer description: Embed accent color as decimal integer (e.g. 5814783 for blue). Convert hex to decimal. image: type: object properties: url: { type: string } thumbnail: type: object properties: url: { type: string } footer: type: object properties: text: { type: string, description: "Footer text (max 2,048 chars)" } icon_url: { type: string } author: type: object properties: name: { type: string, description: Author name (max 256 chars) } url: { type: string } icon_url: { type: string } fields: type: array description: Up to 25 fields per embed maxItems: 25 items: type: object required: [name, value] properties: name: { type: string, description: Field name (max 256 chars) } value: { type: string, description: "Field value (max 1,024 chars)" } inline: { type: boolean, description: Display fields side-by-side } poll: type: object description: Native Discord poll. Cannot be combined with media attachments in the same message. properties: question: type: object required: [text] properties: text: { type: string, description: Poll question (max 300 chars) } answers: type: array description: 1-10 answer options maxItems: 10 items: type: object properties: poll_media: type: object properties: text: { type: string, description: Answer text } duration: type: integer description: Poll duration in hours (1-768). Default 24. minimum: 1 maximum: 768 allow_multiselect: type: boolean description: Allow users to select multiple answers. Default false. crosspost: type: boolean description: Auto-crosspost to every server following this announcement channel (type 5). No-op for regular text channels. forumThreadName: type: string description: Thread title for forum channel posts (type 15). Required when posting to a forum channel. forumAppliedTags: type: array description: Tag snowflake IDs to apply to forum posts. Max 5 tags. maxItems: 5 items: type: string threadFromMessage: type: object description: Create a follow-up thread under the published message. properties: name: type: string description: Thread name (1-100 chars) autoArchiveDuration: type: integer description: Auto-archive after inactivity (minutes) enum: [60, 1440, 4320, 10080] rateLimitPerUser: type: integer description: Slow-mode duration in seconds (0-21600) minimum: 0 maximum: 21600 tts: type: boolean description: Send as text-to-speech message. Discord reads the message aloud in the channel. webhookUsername: type: string description: Override the webhook display name for this post only (1-80 chars). Falls back to the account-level default set via PATCH /v1/connect/discord. webhookAvatarUrl: type: string description: Override the webhook avatar URL for this post only. Falls back to the account-level default. description: | Discord message settings. Supports plain text (2,000 chars), rich embeds (up to 10), native polls, forum posts, threads, and announcement crossposts. Media attachments support images (JPEG, PNG, GIF, WebP), videos (MP4), and documents (up to 10 files, 25 MB each). Webhook identity (username + avatar) can be customized per-account via PATCH /v1/connect/discord or per-post via webhookUsername/webhookAvatarUrl. SlackPlatformData: type: object properties: threadTs: type: string description: 'Parent message ts to post this message as a thread reply (e.g. "1503435956.000247").' unfurlLinks: type: boolean description: 'Expand links in the message into preview cards. Default true.' unfurlMedia: type: boolean description: 'Expand media links into inline previews. Default true.' username: type: string description: 'Override the bot display name for this message only (requires no setup; shown with an APP badge). Does not change the app identity in the sidebar.' iconUrl: type: string description: 'Override the bot avatar image URL for this message only.' description: | Slack message settings. Posts mrkdwn text (up to 40,000 chars; Slack truncates beyond that) to the channel fixed by the connected account, with up to 10 media files per post uploaded via Slack's file API (the text becomes the caption). The target channel is chosen at connect time — one connected account per channel — so channelId is NOT accepted here (a 400 is returned); connect the desired channel via /v1/connect/slack and target its accountId. Messages over 4,000 characters cannot be edited later (Slack's edit limit is stricter than its post limit). DiscordScheduledEvent: type: object description: | Discord guild scheduled event. Returned by /v1/discord/guilds/{guildId}/events endpoints. Fields below are the subset Zernio consumes — Discord may return more (e.g. creator, image hash) which we pass through verbatim. properties: id: { type: string, description: Event snowflake ID } guild_id: { type: string } channel_id: { type: [string, "null"], description: Voice/stage channel ID; null for external events. } creator_id: { type: [string, "null"] } name: { type: string } description: { type: [string, "null"] } scheduled_start_time: { type: string, format: date-time } scheduled_end_time: { type: [string, "null"], format: date-time, description: Required for external events; optional for voice/stage. } privacy_level: { type: integer, enum: [2], description: Always 2 (GUILD_ONLY) — Discord deprecated PUBLIC events. } status: type: integer enum: [1, 2, 3, 4] description: "1=SCHEDULED, 2=ACTIVE, 3=COMPLETED, 4=CANCELED" entity_type: type: integer enum: [1, 2, 3] description: "1=STAGE_INSTANCE, 2=VOICE, 3=EXTERNAL" entity_id: { type: [string, "null"] } entity_metadata: type: [object, "null"] properties: location: { type: string, description: External event location string. } user_count: { type: integer, description: Number of members who RSVP'd. Only present when withUserCount=true on list. } image: { type: [string, "null"], description: Cover image hash; build URL via cdn.discordapp.com. } QueueSlot: type: object properties: dayOfWeek: type: integer description: Day of week (0=Sunday, 6=Saturday) minimum: 0 maximum: 6 time: type: string description: Time in HH:mm format (24-hour) pattern: '^([0-1][0-9]|2[0-3]):[0-5][0-9]$' QueueSchedule: type: object properties: _id: type: string description: Unique queue identifier profileId: type: string description: Profile ID this queue belongs to name: type: string description: Queue name (e.g., "Morning Posts", "Evening Content") timezone: type: string description: IANA timezone (e.g., America/New_York) slots: type: array items: $ref: '#/components/schemas/QueueSlot' active: type: boolean description: Whether the queue is active isDefault: type: boolean description: Whether this is the default queue for the profile (used when no queueId specified) createdAt: type: string format: date-time updatedAt: type: string format: date-time Pagination: type: object properties: page: { type: integer } limit: { type: integer } total: { type: integer } pages: { type: integer } Profile: type: object properties: _id: { type: string } userId: { type: string } name: { type: string } description: { type: string } color: { type: string } isDefault: { type: boolean } isOverLimit: type: boolean description: Only present when includeOverLimit=true. Indicates if this profile exceeds the plan limit. createdAt: { type: string, format: date-time } SocialAccount: type: object required: [_id, platform, profileId, isActive] properties: _id: { type: string } platform: type: string enum: [tiktok, instagram, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat, discord, slack, whatsapp, linkedinads, metaads, pinterestads, tiktokads, xads, googleads, openaiads] profileId: oneOf: - type: string - $ref: '#/components/schemas/Profile' username: { type: string } displayName: { type: string } profilePicture: type: [string, "null"] description: URL to the account's profile picture on the platform. May be null if the platform does not provide one. profileUrl: type: string description: Full profile URL for the connected account on its platform. isActive: { type: boolean } needsReconnection: type: boolean description: | The platform definitively reported the stored OAuth token as dead. While true, GET /v1/connect/{platform}/ads returns a fresh authUrl (implicit force=true) instead of alreadyConnected, so re-running the connect flow recovers the account. Cleared automatically when the account is re-authorized. followersCount: type: number description: Follower count (only included if user has analytics add-on) followersLastUpdated: type: string format: date-time description: Last time follower count was updated (only included if user has analytics add-on) parentAccountId: type: [string, "null"] description: | Reference to the parent posting SocialAccount. Set for ads accounts that share or derive from a posting account's OAuth token. null for standalone ads (Google Ads) and all posting accounts. enabled: type: boolean description: | Whether the user explicitly activated this account. false means the account was created as a side effect (e.g., posting account auto-created when user connected ads first). Posting UI and scheduler ignore accounts with enabled: false. metadata: type: object description: | Platform-specific metadata. Fields vary by platform. For WhatsApp accounts, includes: - qualityRating: Phone number quality rating from Meta (GREEN, YELLOW, RED, or UNKNOWN) - nameStatus: Display name review status (APPROVED, PENDING_REVIEW, DECLINED, or NONE). A declined or pending display name does not by itself block sending; sendability is reported separately via health_status (can_send_message). - messagingLimitTier: Maximum unique business-initiated conversations per 24h rolling window (TIER_250, TIER_1K, TIER_10K, TIER_100K, or TIER_UNLIMITED). Scales automatically as quality rating improves. - verifiedName: Meta-verified business display name - displayPhoneNumber: Formatted phone number (e.g., "+1 555-123-4567") - wabaId: WhatsApp Business Account ID - phoneNumberId: Meta phone number ID For LinkedIn accounts, profileData carries the profile details refreshed on each daily snapshot: - profileData.bio: The member's headline for personal accounts, or the organization description for organization accounts. null when the member has not set one. - profileData.extraData.vanityName: The member's profile slug, i.e. the /in/{vanityName} segment of profileUrl. Personal accounts only; an organization's own slug is in metadata.organizationInfo.vanityName. AccountWithFollowerStats: allOf: - $ref: '#/components/schemas/SocialAccount' - type: object properties: currentFollowers: { type: number, description: Current follower count } lastUpdated: { type: string, format: date-time } growth: { type: number, description: Follower change over period } growthPercentage: { type: number, description: Percentage growth } dataPoints: { type: number, description: Number of historical snapshots } accountStats: type: object description: | Platform-specific account stats from the latest daily snapshot. Fields vary by platform. Only present if metadata has been captured. properties: followingCount: { type: number, description: Number of accounts being followed } mediaCount: { type: number, description: Total media posts (Instagram) } videoCount: { type: number, description: "Total videos (YouTube, TikTok)" } tweetCount: { type: number, description: Total tweets (X/Twitter) } postsCount: { type: number, description: Total posts (Bluesky) } pinCount: { type: number, description: Total pins (Pinterest) } totalViews: { type: number, description: Total channel views (YouTube) } likesCount: { type: number, description: Total likes received (TikTok) } monthlyViews: { type: number, description: Monthly profile views (Pinterest) } listedCount: { type: number, description: Lists the user appears on (X/Twitter) } boardCount: { type: number, description: Total boards (Pinterest) } ApiKey: type: object properties: id: { type: string } name: { type: string } keyPreview: { type: string } expiresAt: { type: string, format: date-time } createdAt: { type: string, format: date-time } key: type: string description: Returned only once, on creation scope: type: string enum: [full, profiles] description: "'full' grants access to all profiles, 'profiles' restricts to specific profiles" default: full profileIds: type: array items: type: object properties: _id: { type: string } name: { type: string } color: { type: string } description: Profiles this key can access (populated with name and color). Only present when scope is 'profiles'. permission: type: string enum: [read-write, read] description: "'read-write' allows all operations, 'read' restricts to GET requests only" default: read-write disabledResourceGroups: type: array items: type: string enum: [publishing, engagement, messages, contacts, analytics, ads, telephony, accounts, billing, webhooks] description: >- Resource groups this key can NOT access (opt-out denylist). Absent or empty means legacy full access. A key with any group disabled is a restricted key (zrk_ prefix) and can never manage API keys, invites, or member identity. Each operation's group is published as x-resource-group. With 'messages' disabled, the key cannot read or send private messages through any API surface, and it cannot create or edit a webhook subscription broader than itself: it cannot subscribe to, test-fire, redeliver, or read delivery logs for message events. Subscriptions created earlier, from the dashboard, or with a full-access key keep delivering whatever their own `disabledResourceGroups` allows, so restricting an existing integration end to end means restricting the subscription too. OAuth connector tokens (AI assistants and MCP clients) resolve against the same registry, but their groups are not settable yet: treat an authorized connector as full access. ConnectedApp: type: object description: | An OAuth client (AI assistant / MCP connector) authorized by the user and still holding at least one live token. properties: clientId: { type: string } clientName: type: string description: 'Name the client declared at registration. Registration is open, so this is self-declared and not verified.' redirectHost: type: [string, "null"] description: 'Host of the client''s registered redirect URI (non-http schemes are shown as scheme//host). The destination an impostor cannot fake.' scopes: type: array items: { type: string } description: Scopes granted on the most recent token. authorizedAt: { type: [string, "null"], format: date-time } lastUsedAt: type: [string, "null"] format: date-time description: Last time any of the client's live tokens authenticated a request. tokenCount: type: integer description: 'Live tokens held by the client (an active session is typically one access plus one refresh token).' BillingSnapshot: type: object description: | Account billing state — plan, cycle, balance, spend caps, and payment / access status. Returned by `GET /v1/billing`. properties: billingSystem: type: string enum: [metronome, stripe] plan: type: object properties: name: { type: string } isUsageBased: { type: boolean } period: type: object description: Current billing cycle. `start`/`end` are resolved for usage-based accounts only. properties: start: { type: [string, "null"], format: date-time } end: { type: [string, "null"], format: date-time } anchorDay: { type: integer, description: Day-of-month the cycle resets. } balance: type: [object, "null"] description: Accrued spend + remaining credits this cycle. `null` for fixed-subscription (Stripe) plans. properties: accruedThisPeriodCents: { type: integer } creditsRemainingCents: { type: integer } caps: type: object properties: xSpendUsedCents: { type: integer } xSpendLimitCents: { type: [integer, "null"], description: Monthly X-API spend cap; null = unlimited. } status: type: object properties: hasAccess: { type: boolean } suspended: { type: boolean } suspendedAt: { type: [string, "null"], format: date-time } suspensionReason: { type: [string, "null"] } openInvoiceUrl: { type: [string, "null"], description: Hosted invoice URL for dunning (Stripe). } declineReason: { type: [string, "null"] } autoUpgradeEnabled: { type: boolean } legacy: type: object description: Deprecated plan entitlements (Stripe only); absent for usage-based accounts. properties: limits: type: object properties: uploads: { type: integer } profiles: { type: integer } UsageMetering: type: object description: | Billed spend by product family over a window, from Metronome's invoice breakdown (the CHARGE view). Returned by `GET /v1/usage`. properties: supported: type: boolean description: False for legacy Stripe accounts (no Metronome invoice to split); `days` and `totals` are then empty/zero. granularity: type: string enum: [day, month, total] days: type: array description: One row per bucket. Empty when `granularity=total`. `date` is a UTC date (month buckets use the 1st). items: type: object properties: date: { type: string, format: date } accounts: { type: number } numbers: { type: number } calls: { type: number } sms: { type: number } dlc: { type: number, description: 10DLC registration (brand + campaign) fees. } xApi: { type: number } credits: { type: number, description: Applied credits/discounts (negative). } other: { type: number } totals: type: object description: Sum of each product over the whole window (USD), plus `total`. Unaffected by `granularity`. properties: accounts: { type: number } numbers: { type: number } calls: { type: number } sms: { type: number } dlc: { type: number } xApi: { type: number } credits: { type: number } other: { type: number } total: { type: number } lineItems: type: array description: Per-invoice-line-item rows (largest spend first) for a detailed breakdown. items: type: object properties: name: { type: string } product: type: string enum: [accounts, numbers, calls, sms, dlc, xApi, credits, other] totalUsd: { type: number } quantity: { type: number } peaks: type: object description: Peak counts over the window (Metronome COUNT metrics + live active-number count). properties: accounts: { type: integer } numbers: { type: integer } callUsage: type: object description: Billable call volumes over the window. properties: whatsapp: type: object properties: count: { type: integer } minutes: { type: integer } pstn: type: object properties: count: { type: integer } minutes: { type: integer } period: type: object properties: start: { type: string, format: date-time } end: { type: string, format: date-time } source: type: string enum: [cycle, window] description: '`cycle` = a real billing period resolved; `window` = trailing/custom window (or cycle fallback).' tax: type: [object, "null"] description: | Estimated tax on the window's net `totals.total`, computed with Stripe Tax against the billing address (the same engine the real invoice uses; invoices apply exclusive tax, so the card is charged total + tax). Null when the account has no billing address on file, the total is zero or negative, or the estimate failed. properties: taxUsd: { type: number, description: "Estimated tax in USD, added on top of `totals.total`." } ratePercent: { type: [number, "null"], description: "Combined rate percentage, e.g. 21." } jurisdictionLabel: { type: [string, "null"], description: 'Human jurisdiction label, e.g. "ES VAT" or "WA sales tax".' } reverseCharge: { type: boolean, description: True for EU/UK B2B reverse charge (0 tax added by design). } UsageStats: type: object description: | Plan and usage stats. The response shape depends on `billingSystem`: * Stripe users (default): per-period counters like `usage.uploads` and `usage.profiles` are returned, scoped by the plan's `limits`. * Metronome users (usage-based): `limits` are unlimited (-1). The `usage` block carries connected-account and per-X-operation counts, and the `spend` block carries current-period costs plus the X cap. properties: billingSystem: type: string enum: [stripe, metronome] description: Which billing system the account is on. Shape of `usage`/`spend` differs. planName: { type: string } billingPeriod: { type: string, enum: [monthly, yearly] } signupDate: { type: string, format: date-time } billingAnchorDay: { type: integer, description: "Day of month (1-31) when the billing cycle resets" } hasAccess: type: boolean description: True if the account is in good standing. False for past-due/unpaid/paused subscriptions. customerId: type: [string, "null"] description: Stripe customer ID, when present. isInvitedUser: type: boolean description: True if this is a team member; limits/usage reflect the account owner. autoUpgradeEnabled: type: boolean description: Stripe-only. Always false for Metronome users. limits: type: object description: Plan limits. For Metronome users both fields are `-1` (unlimited). properties: uploads: { type: integer } profiles: { type: integer } usage: type: object description: | Per-period usage counts. Fields present depend on `billingSystem`: Stripe returns `uploads` / `profiles` / `lastReset`; Metronome returns `connectedAccounts` / `xApiCalls` / `xApiCallsByOperation`. properties: # Stripe fields uploads: { type: integer, description: "Stripe users only. Uploads consumed in the current period." } profiles: { type: integer, description: "Stripe users only. Profiles currently owned." } lastReset: { type: string, format: date-time, description: "Stripe users only." } # Metronome fields connectedAccounts: type: integer description: "Metronome users only. Accounts currently connected across the team." xApiCalls: type: object deprecated: true description: | **Deprecated.** Legacy 3-tier aggregate. Operations outside the three historical prices ($0.005/$0.010/$0.015) — notably the $0.200 "Posts with URL" tier added April 2026 — are silently excluded from this shape. Use `xApiCallsByOperation` instead; it captures every tier and is the source of truth for per-operation call counts. properties: x_api_005: { type: integer, description: "Calls at $0.005 per call (reads, lists, bookmarks, content manage, etc.)" } x_api_010: { type: integer, description: "Calls at $0.010 per call (user reads, DM reads, follow reads, trends, list create, privacy update)" } x_api_015: { type: integer, description: "Calls at $0.015 per call (posts/replies, DM sends, user interactions)" } xApiCallsByOperation: type: object additionalProperties: type: integer description: | Metronome users only. Per-operation X API call counts keyed by operation (e.g. `posts_read`, `content_create`, `content_create_with_url`). Resolve each key to price and metadata via `GET /v1/billing/x-pricing`. This is the canonical source — covers every price tier including the $0.200 URL tier that `xApiCalls` excludes. example: posts_read: 42 content_create: 7 content_create_with_url: 3 dm_interaction_create: 1 spend: type: object description: "Metronome users only. Current-period spend summary." properties: currentPeriodCents: type: integer description: Total current-period spend in cents (all products combined). creditsRemainingCents: type: integer description: Free-tier credit remaining in cents. Applied before any charge. xSpendCents: type: integer description: | Current-period X/Twitter API spend in cents, summed from `xApiCallsByOperation` × per-operation prices. Tier-agnostic (covers every price including the $0.200 URL tier). Rounded up for conservative enforcement against `xSpendLimitCents`. xSpendLimitCents: type: [integer, "null"] description: | Monthly X spend cap set by the account owner, or null if no cap. When current X spend hits this cap, analytics and inbox sync are auto-paused for X accounts. Publishing is never blocked by this cap. XApiPricing: type: object description: | Canonical X/Twitter API pricing table. Zernio passes X API costs through at exact rates with zero markup, so every call you make has a known per-unit price. Use this payload alongside `/v1/usage-stats` (which returns per-operation call counts via `xApiCallsByOperation`) to compute exact cost attribution by X action. properties: currency: { type: string, example: USD } markup: { type: string, example: "0%", description: "Always 0% — Zernio does not mark up X API rates." } source: { type: string, format: uri, example: "https://developer.x.com/#pricing" } lastVerified: type: string format: date description: Date the prices were last verified against X's published rates. tiers: type: array description: Rollup of operations grouped by their per-call price. items: type: object properties: tier: type: string description: | Tier key derived from price (e.g. `x_api_005` for $0.005, `x_api_200` for $0.200). The first three keys map to the legacy `xApiCalls` aggregate; new tiers (e.g. `x_api_200` for the URL tier added April 2026) are surfaced here but not in the legacy shape. example: x_api_005 pricePerCallUsd: { type: number, example: 0.005 } operationCount: { type: integer, example: 13 } operations: type: array description: Flat list of every X operation Zernio can perform, with its rate. items: { $ref: '#/components/schemas/XApiOperation' } XApiOperation: type: object description: A single X API operation with its per-call price and the Zernio platform methods that trigger it. properties: operation: type: string example: posts_read description: Internal operation key. Matches keys in `xApiCallsByOperation`. eventType: type: string example: x_posts_read description: Metronome `event_type` emitted when this operation runs. displayName: type: string example: "X API: Posts Read" description: Human-readable label shown on Metronome invoices. pricePerCallUsd: type: number example: 0.005 pricePerCallCents: type: number example: 0.5 description: Per-call price in cents. Fractional values are intentional. tier: type: string description: | Tier key derived from `pricePerCallUsd` (e.g. `x_api_005` for $0.005, `x_api_200` for $0.200). Useful for grouping operations by price in dashboards. example: x_api_005 triggeredBy: type: array description: Zernio platform methods that emit this operation, with their metering rule. items: type: object properties: method: type: string example: getPostAnalytics description: Zernio platform method name. metering: type: string enum: [always, analytics_optin, inbox_optin, absorbed] description: | When the method actually bills the user: * `always` — every call is metered * `analytics_optin` — only when the X account has analytics enabled * `inbox_optin` — only when the X account has inbox sync enabled * `absorbed` — Zernio eats the cost, never billed PostAnalytics: type: object properties: impressions: { type: integer, example: 0 } reach: { type: integer, example: 0 } likes: { type: integer, example: 0 } comments: { type: integer, example: 0 } shares: { type: integer, example: 0 } saves: { type: integer, example: 0, description: 'Number of saves/bookmarks (Instagram, Pinterest)' } clicks: { type: integer, example: 0 } views: { type: integer, example: 0 } follows: { type: integer, example: 0, description: 'Instagram feed posts and stories only: organic accounts that started following from this post. 0 for reels and other platforms.' } igReelsAvgWatchTime: { type: integer, example: 0, description: 'Instagram Reels only: average watch time per play, in milliseconds. 0 for non-Reels media and other platforms.' } igReelsVideoViewTotalTime: { type: integer, example: 0, description: 'Instagram Reels only: total watch time including replays, in milliseconds. 0 for non-Reels media and other platforms.' } videoDurationSeconds: { type: [integer, "null"], example: 30, description: 'Video length in seconds. Currently Instagram Reels only; combine with igReelsAvgWatchTime (ms) to estimate retention. Null when unknown (other platforms, non-video media, or when Instagram does not expose the media URL, e.g. reels with copyrighted audio).' } engagementRate: { type: number, example: 0 } lastUpdated: { type: string, format: date-time } PlatformAnalytics: type: object properties: platform: { type: string } status: { type: string, enum: [published, failed] } platformPostId: { type: [string, "null"], description: 'The native post ID on the platform (e.g. Instagram media ID, tweet ID)' } accountId: { type: string } accountUsername: { type: [string, "null"] } analytics: anyOf: - $ref: '#/components/schemas/PostAnalytics' - type: "null" syncStatus: { type: string, enum: [synced, pending, unavailable], description: 'Sync state of analytics for this platform' } platformPostUrl: { type: [string, "null"], format: uri } errorMessage: { type: [string, "null"], description: 'Error details when status is failed' } AnalyticsOverview: type: object properties: totalPosts: { type: integer } publishedPosts: { type: integer } scheduledPosts: { type: integer } lastSync: { type: [string, "null"], format: date-time } dataStaleness: type: object properties: staleAccountCount: { type: integer, description: 'Number of accounts with stale analytics data' } syncTriggered: { type: boolean, description: 'Whether a background sync was triggered for stale accounts' } AnalyticsSinglePostResponse: type: object properties: postId: { type: string } latePostId: { type: [string, "null"], description: 'Original Zernio post ID if scheduled via Zernio' } status: { type: string, enum: [published, failed, partial], description: 'Overall post status. "partial" when some platforms published and others failed.' } content: { type: string } scheduledFor: { type: string, format: date-time } publishedAt: { type: [string, "null"], format: date-time } analytics: $ref: '#/components/schemas/PostAnalytics' platformAnalytics: type: array items: $ref: '#/components/schemas/PlatformAnalytics' platform: { type: string } platformPostUrl: { type: [string, "null"], format: uri } isExternal: { type: boolean } syncStatus: { type: string, enum: [synced, pending, partial, unavailable], description: 'Overall sync state across all platforms' } message: { type: [string, "null"], description: 'Human-readable status message for pending, partial, or failed states' } thumbnailUrl: { type: [string, "null"], format: uri } mediaType: { type: [string, "null"], enum: [image, video, carousel, text] } mediaItems: type: array description: All media items for this post. Carousel posts contain one entry per slide. items: type: object properties: type: { type: string, enum: [image, video] } url: { type: string, format: uri, description: Direct URL to the media } thumbnail: { type: string, format: uri, description: Thumbnail URL (same as url for images) } altText: type: string description: Accessibility alt text set on the media, when present. AnalyticsListResponse: type: object properties: overview: $ref: '#/components/schemas/AnalyticsOverview' posts: type: array items: type: object properties: _id: { type: string } latePostId: { type: [string, "null"], description: 'Original Zernio post ID if scheduled via Zernio' } content: { type: string } scheduledFor: { type: string, format: date-time } publishedAt: { type: string, format: date-time } status: { type: string } analytics: $ref: '#/components/schemas/PostAnalytics' platforms: type: array items: $ref: '#/components/schemas/PlatformAnalytics' platform: { type: string } platformPostUrl: { type: string, format: uri } isExternal: { type: boolean } profileId: { type: [string, "null"] } thumbnailUrl: { type: string, format: uri } mediaType: { type: string, enum: [image, video, gif, document, carousel, text] } mediaItems: type: array description: All media items for this post. Carousel posts contain one entry per slide. items: type: object properties: type: { type: string, enum: [image, video] } url: { type: string, format: uri, description: Direct URL to the media } thumbnail: { type: string, format: uri, description: Thumbnail URL (same as url for images) } altText: type: string description: Accessibility alt text set on the media, when present. pagination: $ref: '#/components/schemas/Pagination' accounts: type: array description: Connected social accounts (followerCount and followersLastUpdated only included if user has analytics add-on) items: $ref: '#/components/schemas/SocialAccount' hasAnalyticsAccess: type: boolean description: Whether user has analytics add-on access # LinkedIn Aggregate Analytics Responses LinkedInAggregateAnalyticsTotalResponse: type: object description: Response for TOTAL aggregation (lifetime totals) properties: accountId: { type: string } platform: { type: string, example: linkedin } accountType: { type: string, example: personal } username: { type: string } aggregation: { type: string, enum: [TOTAL] } dateRange: type: [object, "null"] properties: startDate: { type: string, format: date } endDate: { type: string, format: date } analytics: type: object properties: impressions: { type: integer, description: Total impressions across all posts } reach: { type: integer, description: Unique members reached across all posts } reactions: { type: integer, description: Total reactions across all posts } comments: { type: integer, description: Total comments across all posts } shares: { type: integer, description: Total reshares across all posts } saves: { type: integer, description: Total times posts were saved (personal accounts only) } sends: { type: integer, description: Total times posts were sent via LinkedIn messaging (personal accounts only) } engagementRate: { type: number, description: Overall engagement rate as percentage } note: { type: string } lastUpdated: { type: string, format: date-time } LinkedInAggregateAnalyticsDailyResponse: type: object description: Response for DAILY aggregation (time series breakdown) properties: accountId: { type: string } platform: { type: string, example: linkedin } accountType: { type: string, example: personal } username: { type: string } aggregation: { type: string, enum: [DAILY] } dateRange: type: [object, "null"] properties: startDate: { type: string, format: date } endDate: { type: string, format: date } analytics: type: object description: Daily breakdown of each metric as date/count pairs. Reach not available with DAILY aggregation. properties: impressions: type: array items: type: object properties: date: { type: string, format: date } count: { type: integer } reactions: type: array items: type: object properties: date: { type: string, format: date } count: { type: integer } comments: type: array items: type: object properties: date: { type: string, format: date } count: { type: integer } shares: type: array items: type: object properties: date: { type: string, format: date } count: { type: integer } saves: type: array description: Daily saves (personal accounts only) items: type: object properties: date: { type: string, format: date } count: { type: integer } sends: type: array description: Daily sends via LinkedIn messaging (personal accounts only) items: type: object properties: date: { type: string, format: date } count: { type: integer } skippedMetrics: type: array description: Metrics that were skipped due to API limitations items: { type: string } note: { type: string } lastUpdated: { type: string, format: date-time } # ============================================ # Response Schemas # ============================================ # Posts Responses PostsListResponse: type: object properties: posts: type: array items: $ref: '#/components/schemas/Post' pagination: $ref: '#/components/schemas/Pagination' PostGetResponse: type: object properties: post: $ref: '#/components/schemas/Post' PostCreateResponse: type: object properties: message: type: string post: $ref: '#/components/schemas/Post' PostUpdateResponse: type: object properties: message: type: string post: $ref: '#/components/schemas/Post' warnings: type: array items: type: string PostDeleteResponse: type: object properties: message: type: string PostRetryResponse: type: object properties: message: type: string post: $ref: '#/components/schemas/Post' # Profiles Responses ProfilesListResponse: type: object properties: profiles: type: array items: $ref: '#/components/schemas/Profile' total: type: integer description: 'Total matching profiles across all pages. Present only when limit or skip was passed.' skip: type: integer description: 'Offset applied. Present only when limit or skip was passed.' limit: type: integer description: Echo of the limit query param. Present only when it was passed. ProfileCreateResponse: type: object properties: message: type: string profile: $ref: '#/components/schemas/Profile' ProfileGetResponse: type: object properties: profile: $ref: '#/components/schemas/Profile' ProfileUpdateResponse: type: object properties: message: { type: string } profile: $ref: '#/components/schemas/Profile' ProfileDeleteResponse: type: object properties: message: { type: string } AccountsListResponse: type: object required: [accounts, hasAnalyticsAccess] properties: accounts: type: array items: { $ref: '#/components/schemas/SocialAccount' } hasAnalyticsAccess: type: boolean description: Whether user has analytics add-on access pagination: description: Only present when page/limit params are provided $ref: '#/components/schemas/Pagination' FollowerStatsResponse: type: object properties: accounts: type: array items: $ref: '#/components/schemas/AccountWithFollowerStats' stats: type: object additionalProperties: type: array items: type: object properties: date: { type: string, format: date } followers: { type: number } dateRange: type: object properties: from: { type: string, format: date-time } to: { type: string, format: date-time } granularity: { type: string } UploadedFile: type: object properties: type: type: string enum: [image, video, document] url: { type: string, format: uri } filename: { type: string } size: { type: integer } mimeType: { type: string } MediaUploadResponse: type: object properties: files: type: array items: $ref: '#/components/schemas/UploadedFile' UploadTokenResponse: type: object properties: token: { type: string } uploadUrl: { type: string, format: uri } expiresAt: { type: string, format: date-time } status: type: string enum: [pending, completed, expired] UploadTokenStatusResponse: type: object properties: token: { type: string } status: type: string enum: [pending, completed, expired] files: type: array items: $ref: '#/components/schemas/UploadedFile' createdAt: { type: string, format: date-time } expiresAt: { type: string, format: date-time } completedAt: { type: string, format: date-time } QueueSlotsResponse: type: object description: Single queue response (default behavior) properties: exists: { type: boolean } schedule: $ref: '#/components/schemas/QueueSchedule' nextSlots: type: array items: { type: string, format: date-time } QueueUpdateResponse: type: object properties: success: { type: boolean } schedule: $ref: '#/components/schemas/QueueSchedule' nextSlots: type: array items: { type: string, format: date-time } reshuffledCount: { type: integer } skippedDailyLimit: { type: integer } isNewQueue: { type: boolean } QueueDeleteResponse: type: object properties: success: { type: boolean } deleted: { type: boolean } deletedCount: { type: integer } message: { type: string } QueuePreviewResponse: type: object properties: profileId: { type: string } queueId: { type: string } queueName: { type: string } count: { type: integer } slots: type: array items: { type: string, format: date-time } QueueNextSlotResponse: type: object properties: profileId: { type: string } nextSlot: { type: string, format: date-time } timezone: { type: string } queueId: { type: string, description: Queue ID this slot belongs to } queueName: { type: string, description: Queue name } # Users Responses User: type: object properties: _id: type: string email: type: string name: type: string role: type: string createdAt: type: string format: date-time UsersListResponse: type: object properties: users: type: array items: $ref: '#/components/schemas/User' UserGetResponse: type: object properties: user: $ref: '#/components/schemas/User' AdMetrics: type: object properties: spend: { type: number } impressions: { type: integer } reach: type: integer description: "Unique people reached in the requested date range. Meta (facebook/instagram) and TikTok: the platform's own de-duplicated reach for the exact range, fetched live and cached up to ~1 hour (may lag recent delivery; on a transient platform error the value temporarily falls back to a sum of per-day reach, which overcounts people reached on multiple days or by multiple child ads). Because it is de-duplicated, reach is NOT additive on these platforms: neither daily values nor child nodes sum to the range total. Google, LinkedIn, X, Pinterest and OpenAI report 0 (reach not synced). Frequency (impressions / reach) is only meaningful for Meta and TikTok." clicks: { type: integer } ctr: { type: number, description: Click-through rate (%) } cpc: { type: number, description: Cost per click } cpm: { type: number, description: Cost per 1000 impressions } engagement: { type: integer } conversions: type: number description: "Count of conversion events over the requested date range. FRACTIONAL: attribution splits one conversion across touchpoints and Google additionally reports modeled conversions, so values like 0.347 are normal. Meta: events matching the campaign's promoted_object.custom_event_type (PURCHASE, LEAD, etc.). Google: the account's tracked conversions. X and LinkedIn: their reported website/lead conversions (added 2026-07). 0 for non-conversion campaigns or when no events have fired." costPerConversion: type: number description: "Derived spend / conversions in the same currency as spend. 0 when conversions is 0." actions: type: object additionalProperties: type: integer description: "Per-action-type counts summed over the date range, keyed by the platform's action-type names. Meta: raw Insights action_type keys (link_click, offsite_conversion.fb_pixel_purchase, onsite_conversion.lead_grouped, ...) — both engagement and conversion events. X: conversion types (purchase, sign_up, site_visit, download, custom). LinkedIn: conversion types (post_click, post_view, lead_gen). Google returns {} (its per-action names aren't synced per ad). Empty object when no actions are reported. NOTE: keys differ by platform, so branch on the ad's platform when interpreting them." example: link_click: 160 post_engagement: 300 offsite_conversion.fb_pixel_purchase: 42 actionValues: type: object additionalProperties: type: number description: "Monetary mirror of `actions`, from Meta's Insights `action_values[]` array. Same keying — values are the revenue attributed to each action_type, in ad-account native currency (same unit as `spend`; see the campaign node's `currency` field). Use this to compute revenue-per-event (e.g. avg purchase value). Meta-only; other platforms return {}." example: offsite_conversion.fb_pixel_purchase: 2456.78 offsite_conversion.fb_pixel_add_to_cart: 980.50 purchaseValue: type: number description: "Convenience sum of purchase-type action values — picked from `actionValues` via the same priority list as `conversions` so both fields describe the same events. In ad-account native currency. 0 when the campaign has no purchase event configured. Meta-only." roas: type: number description: "Return on ad spend — derived as `purchaseValue / spend`. 0 when `spend` is 0. Equivalent to Meta's `purchase_roas` under default attribution. At ad-set and campaign levels this is recomputed from summed purchaseValue + spend (NOT averaged across children) so it's mathematically correct at every rollup level." videoPlayActions: type: integer description: "Meta video ads only (0 for non-video ads and other platforms), like all video* fields below. Number of times the video started playing (Meta `video_play_actions`), summed over the date range and across children at ad-set/campaign level." video30SecWatchedActions: { type: integer, description: "Views of at least 30 seconds (or to the end, for shorter videos). Meta `video_30_sec_watched_actions`." } videoThruplayWatchedActions: { type: integer, description: "ThruPlays (watched to completion, or at least 15 seconds). Meta `video_thruplay_watched_actions`." } videoP25WatchedActions: { type: integer, description: "Views reaching 25% of the video's length. With the other percentile fields, powers hook/hold/drop-off analysis (e.g. hook rate = videoP25WatchedActions / videoPlayActions). Meta `video_p25_watched_actions`." } videoP50WatchedActions: { type: integer, description: "Views reaching 50% of the video's length. Meta `video_p50_watched_actions`." } videoP75WatchedActions: { type: integer, description: "Views reaching 75% of the video's length. Meta `video_p75_watched_actions`." } videoP95WatchedActions: { type: integer, description: "Views reaching 95% of the video's length. Meta `video_p95_watched_actions`." } videoP100WatchedActions: { type: integer, description: "Views reaching 100% of the video's length. Meta `video_p100_watched_actions`." } videoAvgTimeWatchedActions: type: number description: "Average seconds watched per play (Meta `video_avg_time_watched_actions`). Aggregated over date ranges and across children as a play-weighted average (total watch time / total plays), never a plain average of averages." costPerThruplay: type: number description: "Derived `spend / videoThruplayWatchedActions`, in ad-account native currency. Rounded to 4 decimals rather than the usual 2 because a ThruPlay routinely costs well under a cent. 0 when the ad has no ThruPlays." funnel: $ref: '#/components/schemas/AdFunnelCounts' engagementBreakdown: $ref: '#/components/schemas/AdEngagementCounts' lastSyncedAt: { type: string, format: date-time, description: "Present on individual ads only, not on campaign aggregations" } AdFunnelCounts: type: object description: | Named conversion-funnel steps, resolved from the same data as `actions` so you never have to parse action-type strings yourself. Meta reports one event under several action types at once (`offsite_conversion.fb_pixel_purchase`, `omni_purchase`, `purchase`, …). Each field below takes the FIRST family member present rather than summing them, which is what makes these counts safe to add up — summing the raw `actions` keys yourself double or triple counts. The same priority order backs `conversions`, so a purchase-optimised campaign reports the identical number in `conversions` and `funnel.purchases`. Every field is 0 when that step never fired. Populated for Meta ads; other platforms report a different action taxonomy and generally leave these at 0 (read `actions` for those). At ad-set and campaign level each step is summed from its per-ad values. properties: landingPageViews: { type: integer, description: "Landing page views — the visitor actually loaded the destination, unlike a link click. Meta `landing_page_view`." } contentViews: { type: integer, description: "Content views (Meta `ViewContent` pixel event)." } searches: { type: integer, description: "On-site searches (Meta `Search` pixel event)." } wishlistAdds: { type: integer, description: "Adds to wishlist (Meta `AddToWishlist` pixel event)." } cartAdds: { type: integer, description: "Adds to cart (Meta `AddToCart` pixel event)." } checkoutsInitiated: { type: integer, description: "Checkouts started (Meta `InitiateCheckout` pixel event)." } paymentInfoAdds: { type: integer, description: "Payment details added at checkout (Meta `AddPaymentInfo` pixel event)." } purchases: { type: integer, description: "Purchases (Meta `Purchase` pixel event). Pair with `purchaseValue` for revenue." } leads: { type: integer, description: "Leads, from either the website pixel or an instant form — whichever the ad uses." } registrationsCompleted: { type: integer, description: "Completed registrations (Meta `CompleteRegistration` pixel event)." } appInstalls: { type: integer, description: "Mobile app installs attributed to the ad." } messagingConversationsStarted: { type: integer, description: "Messaging conversations started within 7 days — the headline metric for click-to-WhatsApp and click-to-Messenger ads." } messagingFirstReplies: { type: integer, description: "Messaging threads where the person sent a first reply." } AdEngagementCounts: type: object description: | The single `engagement` total split into the interactions behind it. Note that `engagement` is not the sum of these: Meta's own `post_engagement` and `page_engagement` totals already contain the individual interactions, and all of them are counted into `engagement`. Use these fields when you need a specific interaction, and `engagement` only as the coarse total it has always been. Meta-only; other platforms leave these at 0. properties: postEngagement: { type: integer, description: "Meta's own post-engagement total (`post_engagement`)." } pageEngagement: { type: integer, description: "Meta's own page-engagement total (`page_engagement`)." } reactions: { type: integer, description: "Reactions on the ad's post (`post_reaction`)." } comments: { type: integer, description: "Comments on the ad's post." } shares: { type: integer, description: "Shares of the ad's post. Meta reports these under the action type literally named `post`." } saves: { type: integer, description: "Saves of the ad's post (`onsite_conversion.post_save`)." } pageLikes: { type: integer, description: "New Page likes attributed to the ad (`like`)." } videoViews: { type: integer, description: "3-second video views (`video_view`). For completion-based counts use `videoThruplayWatchedActions`." } linkClicks: { type: integer, description: "Attributed link clicks (`link_click`). This is the attribution-window count, which differs from the in-session `inline_link_clicks` reported by `GET /v1/ads/{adId}/analytics`." } AdDailyMetrics: description: | One day of metrics. Same fields as `AdMetrics` plus the `date` they apply to. Returned inside a node's `daily[]` when `GET /v1/ads/tree` is called with `timeIncrement=1`. Rate metrics (ctr/cpc/cpm/costPerConversion/ roas/videoAvgTimeWatchedActions) are recomputed per day from that day's sums, so summing the additive fields across a node's `daily[]` reproduces its aggregated `metrics` total. `reach` is the exception: on Meta and TikTok the aggregated total is de-duplicated across the range, so daily reach does not sum to it. Do NOT sum or plain-average `videoAvgTimeWatchedActions` across days: the range value is the play-weighted average of the daily values. allOf: - $ref: '#/components/schemas/AdMetrics' - type: object properties: date: { type: string, format: date, description: "Calendar day (YYYY-MM-DD) these metrics apply to." } AdStatus: type: string enum: [active, paused, pending_review, rejected, completed, cancelled, error] AdReviewStatus: type: string enum: [in_review, approved, rejected, with_issues] description: "Platform-side review state, independent of the delivery `status` and the `configuredStatus` on/off toggle. `in_review` means the platform is still reviewing. Absent when the platform reports no review signal (e.g. a paused ad whose review state is masked behind the pause)." BusinessCenter: type: object description: | TikTok Business Center entity. Returned by `GET /v1/ads/business-centers`. BCs are TikTok's agency container — one BC owns N advertisers (ad accounts). Most solo advertisers don't have one; the agency token uses BCs to roll up multi-client access. properties: bcId: type: string description: Business Center ID example: "7123456789012345678" name: type: string description: Display name set by the BC owner example: "Acme Agency" advertiserCount: type: [integer, "null"] description: | Number of advertisers reachable under this BC for the calling token. `null` when the BC asset walk returned empty or failed (typical for agency apps without full BC asset read scope) — distinct from `0`, which would imply the BC genuinely has no advertisers. example: 23 ValueRuleCriterion: type: object additionalProperties: false required: [criteriaType, operator, criteriaValues, criteriaValueTypes] description: | One matching condition inside a value rule. `criteriaValues` and `criteriaValueTypes` are POSITIONALLY paired: same length, same order. properties: id: type: string description: | Platform criterion id. Echo it on `PUT` to KEEP this criterion, omit it to CREATE a new one. A criterion left out of the array entirely is DELETED. criteriaType: type: string enum: [AGE, GENDER, OS_TYPE, DEVICE_PLATFORM, LOCATION, PLACEMENT, OMNI_CHANNEL, AUDIENCE_LABEL] description: | The dimension being matched. `OMNI_CHANNEL` (conversion location: APP, INSTANT_FORM, PHONE_CALL, WEBSITE) is accepted even though Meta's own enum table omits it. operator: type: string enum: [CONTAINS] description: "Required on every criterion. `CONTAINS` is currently the only value Meta supports." criteriaValues: type: array minItems: 1 items: { type: string } description: | The values to match. `AGE` takes ranges such as `18-24`, `18+` or a custom `18-26`; a range whose upper bound is 65 is NOT allowed (use `18+` instead of `18-65`). `LOCATION` takes Targeting-Search keys: a two-letter country code for `LOCATION_COUNTRY`, a numeric key for region / city / comScore market. `AUDIENCE_LABEL` takes labels such as `HIGH_VALUE`, which are applied to a Custom Audience in Ads Manager: there is no API to provision them, so they are passed through unvalidated. criteriaValueTypes: type: array minItems: 1 items: { type: string } description: | One entry per `criteriaValues` entry, in the same order. The literal `"NONE"` for every criteriaType except `LOCATION`, which uses `LOCATION_COUNTRY`, `LOCATION_REGION`, `LOCATION_CITY` or `LOCATION_COMSCORE_MARKET` and MAY mix them within one criterion. `LOCATION_DMA` was replaced by `LOCATION_COMSCORE_MARKET` on 2026-06-22 and is rejected by this API. ValueRule: type: object additionalProperties: false required: [name, adjustSign, adjustValue, criteria] description: | One bid-adjustment rule. Rules are evaluated in ARRAY ORDER and only the first matching rule adjusts the bid for an overlapping audience, so the order is semantic. properties: id: type: string description: | Platform rule id. Echo it on `PUT` to KEEP this rule, omit it to CREATE a new one. A rule left out of the array entirely is DELETED. name: { type: string, minLength: 1, maxLength: 255 } adjustSign: type: string enum: [INCREASE, DECREASE] description: "Direction of the adjustment. There is no signed value field." adjustValue: type: integer minimum: 1 maximum: 1000 description: | Unsigned percentage magnitude. `INCREASE` accepts 1-1000, `DECREASE` accepts 1-90. 0 is out of range on both. status: type: string description: | Meta returns `ACTIVE` here but documents no enum for the field. Treat it as a passthrough: echo whatever the `GET` returned, and do not synthesize values. criteria: type: array minItems: 1 maxItems: 4 items: { $ref: '#/components/schemas/ValueRuleCriterion' } description: "All criteria on a rule must match for the rule to fire." ValueRuleSet: type: object additionalProperties: false required: [id, name, rules] description: | A named set of bid-adjustment rules on an ad account. Attach it to an ad set with `valueRuleSetId`. Limits: 6 sets per ad account, 10 rules per set, 4 criteria per rule. properties: id: { type: string, description: "Platform value rule set id." } name: { type: string } rules: type: array items: { $ref: '#/components/schemas/ValueRule' } description: "Evaluated in order; the first matching rule wins." BidStrategy: type: string enum: [LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS] description: | Meta bid strategy. Same enum applies at campaign and ad-set level; ad-set value (when set) overrides campaign-level. Cross-field rules: - `LOWEST_COST_WITHOUT_CAP` (default): auto-bid, forbids `bidAmount` and `roasAverageFloor`. - `LOWEST_COST_WITH_BID_CAP` / `COST_CAP`: require `bidAmount` (whole currency units). - `LOWEST_COST_WITH_MIN_ROAS`: requires `roasAverageFloor` (decimal multiplier, 2.0 = 2.0x). Source: facebook-business-sdk-codegen api_specs/specs/enum_types.json (`AdSet_bid_strategy`, `Campaign_bid_strategy`). AdBudget: type: object description: Budget amount in the ad account's native currency (see the campaign's `currency` field for the code). required: [amount, type] properties: amount: { type: number } type: { type: string, enum: [daily, lifetime] } TargetingSpec: type: object description: | Normalized, platform-agnostic ad-targeting spec. Every field is optional, an empty object targets the platform's default broadest audience. Field names are camelCase and identical across `POST /v1/ads/create` (the `targeting` object), `POST /v1/ads/targeting/reach-estimate`, and `saved_targeting` audiences, so a spec resolved once can be reused verbatim. Entity ids (`regions[].key`, `cities[].key`, `zips[].key`, `metros[].key`, `interests[].id`, `behaviors[].id`) are the platform's opaque identifiers resolved via `GET /v1/ads/targeting/search`. A spec is therefore meaningful only for the platform it was built against, except the portable fields (`countries`, `ageMin`/`ageMax`, `gender`, `incomeTier`, `languages`) which carry across platforms. Fields a platform cannot honour are rejected at create time with `INVALID_FIELD_VALUE` naming the offending field (not silently dropped). properties: countries: { type: array, items: { type: string }, description: "ISO 3166-1 alpha-2 country codes (e.g. ['US'])." } regions: type: array description: "Region/state targeting. `key` is the platform location ID from /v1/ads/targeting/search?dimension=geo&geoType=region." items: type: object required: [key] properties: key: { type: string } name: { type: string } cities: type: array description: "City targeting. Optional `radius` + `distanceUnit` extend beyond the city limits; both must be set together or both omitted. `radius` is only honoured on platforms whose capability map allows city radius (Meta)." items: type: object required: [key] properties: key: { type: string } name: { type: string } radius: { type: number, description: "Radius around the city. Requires distanceUnit. Meta enforces a minimum city radius (~17 km / 10 mi); smaller values resolve to a 0-size audience and the ad fails at launch. For a tighter catchment use customLocations (lat/lng), which allows a smaller radius." } distanceUnit: { type: string, enum: [mile, kilometer], description: "Required if radius is set." } zips: type: array description: "Postal/ZIP targeting. `key` is the platform's postal location ID (e.g. Meta `US:94304`). Supported on Meta, Google, TikTok, Pinterest, X." items: type: object required: [key] properties: key: { type: string } name: { type: string } metros: type: array description: "DMA / metro-area targeting. `key` is the platform's metro ID (e.g. Meta `DMA:807`)." items: type: object required: [key] properties: key: { type: string } name: { type: string } customLocations: type: array description: "Point-radius (lat/lng) targeting (Meta custom_locations / Google proximity). Honoured only where the capability map allows radius (Meta)." items: type: object required: [latitude, longitude, radius, distanceUnit] properties: latitude: { type: number, minimum: -90, maximum: 90 } longitude: { type: number, minimum: -180, maximum: 180 } radius: { type: number, description: "Positive radius around the point." } distanceUnit: { type: string, enum: [mile, kilometer] } name: { type: string } address: { type: string, description: "Optional label, sent to Meta as `address_string`. latitude/longitude take precedence for the pin location." } excludedLocations: type: object description: "Geo to exclude from the audience. Mirrors the inclusion geo shape: excluded cities can carry a radius catchment and excluded custom (lat/lng) pins are supported, both on Meta (excluded_geo_locations)." properties: countries: { type: array, items: { type: string } } regions: type: array items: type: object required: [key] properties: key: { type: string } name: { type: string } cities: type: array description: "Cities to exclude. Optional `radius` + `distanceUnit` exclude a catchment around the city (both must be set together or both omitted); Meta honours the radius on excluded cities." items: type: object required: [key] properties: key: { type: string } radius: { type: number, description: "Radius around the excluded city. Requires distanceUnit." } distanceUnit: { type: string, enum: [mile, kilometer], description: "Required if radius is set." } zips: type: array items: type: object required: [key] properties: key: { type: string } name: { type: string } places: type: array description: "Named points of interest to exclude. `key` from /v1/ads/targeting/search." items: type: object required: [key] properties: key: { type: string } neighborhoods: type: array description: "Named neighbourhood areas to exclude. `key` from /v1/ads/targeting/search." items: type: object required: [key] properties: key: { type: string } customLocations: type: array description: "Point-radius (lat/lng) pins to exclude (Meta excluded_geo_locations.custom_locations). Mirrors the inclusion customLocations shape." items: type: object required: [latitude, longitude, radius, distanceUnit] properties: latitude: { type: number, minimum: -90, maximum: 90 } longitude: { type: number, minimum: -180, maximum: 180 } radius: { type: number, description: "Positive radius around the point." } distanceUnit: { type: string, enum: [mile, kilometer] } name: { type: string } address: { type: string, description: "Optional label, sent to Meta as `address_string`. latitude/longitude take precedence for the pin location." } ageMin: { type: integer, minimum: 13, maximum: 100 } ageMax: { type: integer, minimum: 13, maximum: 100 } gender: { type: string, enum: [all, male, female], description: "Restrict by gender. 'all' (default) targets everyone. Applied on Meta, TikTok and Pinterest. Ignored on Google, LinkedIn and X." } incomeTier: type: string enum: [top_5, top_10, top_10_25, top_25_50] description: | Normalized household-income tier (ZIP/percentile based). Meta and TikTok express all four. Google maps only `top_10` (its INCOME_RANGE_90_UP); other tiers on Google, and any income tier on LinkedIn / X / Pinterest, are rejected. On Meta, income/zip targeting requires the relevant `specialAdCategories` to be unset (housing/employment/credit ads cannot use it). languages: { type: array, items: { type: string }, description: "Language codes restricting the audience by language. On Meta, ISO 639-1 codes (e.g. ['en']); a bare code targets all regional variants (\"en\" = all English), or use a region-qualified code (\"en_GB\", \"pt_BR\") for a specific one. Unknown codes are rejected." } interests: type: array description: "Interest entities from /v1/ads/targeting/search?dimension=interest. Each carries the platform's opaque id." items: type: object required: [id] properties: id: { type: string } name: { type: string } behaviors: type: array description: "Behaviour entities from /v1/ads/targeting/search?dimension=behavior. Supported on Meta and TikTok." items: type: object required: [id] properties: id: { type: string } name: { type: string } industries: { type: array, items: { type: string }, description: "LinkedIn B2B only. Industry URN id fragments." } companySizes: { type: array, items: { type: string }, description: "LinkedIn B2B only." } seniorities: { type: array, items: { type: string }, description: "LinkedIn B2B only." } jobFunctions: { type: array, items: { type: string }, description: "LinkedIn B2B only." } audienceInclude: { type: array, items: { type: string }, description: "Platform audience IDs to include." } audienceExclude: { type: array, items: { type: string }, description: "Platform audience IDs to exclude." } Ad: type: object properties: _id: { type: string } name: { type: string } platform: { type: string, enum: [facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai] } status: { allOf: [{ $ref: '#/components/schemas/AdStatus' }], description: "Delivery status. Derived from the platform `effective_status`, so it inherits ancestor pauses (an ACTIVE ad under a PAUSED campaign reads `paused`). For the ad's own on/off toggle use `configuredStatus`; for the review state use `reviewStatus`." } configuredStatus: type: [string, "null"] description: "The ad's own on/off toggle as configured on the platform (Meta `configured_status`: ACTIVE / PAUSED), unaffected by ancestor (ad set / campaign) pauses. Distinct from `status`, which is the ancestor-cascaded delivery status. Only present for Meta ads synced after this field was added." example: ACTIVE reviewStatus: allOf: [{ $ref: '#/components/schemas/AdReviewStatus' }] description: "Platform review state of this ad, independent of delivery `status` / `configuredStatus`. Absent when the platform reports no review signal." adType: { type: string, enum: [boost, standalone] } creativeType: type: [string, "null"] enum: [carousel, video, document, image, null] description: "Creative format, classified from the media the creative carries. `null` when the creative carries no media to classify — an unsynced creative and a genuine text-only ad are indistinguishable, so neither is guessed at. Returned by `GET /v1/ads`, `GET /v1/ads/{adId}` and the ad nodes of `GET /v1/ads/tree`." example: video goal: { type: string, enum: [engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales, job_applicants], description: "Available goals vary by platform. Meta (Facebook/Instagram) supports all 9 (incl. `lead_conversion` = website pixel lead optimization and `catalog_sales` = Advantage+ catalog ads). TikTok supports the 7 non-`lead_conversion` goals. LinkedIn supports all except app_promotion / lead_conversion. Twitter/X supports engagement, traffic, awareness, video_views, app_promotion. Pinterest and Google Ads support only engagement, traffic, awareness, video_views." } isExternal: { type: boolean, description: True for ads synced from platform ad managers } budget: type: [object, "null"] properties: amount: { type: number } type: { type: string, enum: [daily, lifetime] } metrics: anyOf: - $ref: '#/components/schemas/AdMetrics' - type: "null" platformAdId: { type: string } platformAdAccountId: { type: string } platformCampaignId: { type: string } platformAdSetId: { type: string } campaignName: { type: string } adSetName: { type: string } platformObjective: type: [string, "null"] description: "Raw Meta campaign objective (e.g. OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_TRAFFIC). Only present for Meta ads." example: OUTCOME_SALES optimizationGoal: type: [string, "null"] description: | What the delivery system optimizes for, at ad-set level. The value space depends on `platform`: - Meta: ad set `optimization_goal` (e.g. OFFSITE_CONVERSIONS, VALUE, LEAD_GENERATION, LINK_CLICKS). - LinkedIn: the campaign's EFFECTIVE `optimizationTargetType`, refreshed from LinkedIn on every sync rather than echoing what was passed on create. `NONE` means manual bidding, and it is a real value, not missing data. Auto-bid values are MAX_IMPRESSION / MAX_CLICK / MAX_CONVERSION / MAX_VIDEO_VIEW / MAX_LEAD / MAX_REACH; target-cost values are TARGET_COST_PER_CLICK / TARGET_COST_PER_IMPRESSION / TARGET_COST_PER_VIDEO_VIEW; cost-cap values are the CAP_COST_AND_MAXIMIZE_* family. example: OFFSITE_CONVERSIONS costType: type: [string, "null"] description: | LinkedIn only. The campaign's EFFECTIVE cost model (billing event) as applied by LinkedIn, refreshed on every sync rather than echoing what was passed on create. One of `CPM` (cost per thousand impressions), `CPC` (cost per click) or `CPV` (cost per video view). On LinkedIn this is the axis that pairs with `bidAmount`; there is no `bidStrategy`. For campaign type SPONSORED_INMAILS, `CPM` bills as cost-per-send x 1000. `null` for non-LinkedIn ads. example: CPC servingStatuses: type: array items: { type: string } description: | LinkedIn only. Why the parent campaign is (or is not) delivering, verbatim from LinkedIn. A campaign can report `status: ACTIVE` and still serve nothing; this array is what says so. - `[]` means no serving data: a non-LinkedIn ad, or a LinkedIn ad not yet re-synced. - `["RUNNABLE"]` means the campaign is eligible to serve. - Anything else is a hold. Known values include ACCOUNT_SERVING_HOLD, ACCOUNT_TOTAL_BUDGET_HOLD, ACCOUNT_END_DATE_HOLD, CAMPAIGN_START_DATE_HOLD, CAMPAIGN_END_DATE_HOLD, CAMPAIGN_TOTAL_BUDGET_HOLD, CAMPAIGN_AUDIENCE_COUNT_HOLD, CAMPAIGN_GROUP_START_DATE_HOLD, CAMPAIGN_GROUP_END_DATE_HOLD, CAMPAIGN_GROUP_TOTAL_BUDGET_HOLD, CAMPAIGN_GROUP_STATUS_HOLD and STOPPED. The list is open on purpose, so treat unrecognized values as holds rather than errors. The end-date and total-budget holds are terminal and surface as `status: completed`; the rest surface as `status: paused`. Note that a hold is not the only cause of zero delivery: with manual, target-cost or cost-cap bidding, a `bidAmount` of 0 stops delivery while `servingStatuses` still reads `["RUNNABLE"]`. Check `costType` / `bidAmount` / `optimizationGoal` as well. example: ["ACCOUNT_TOTAL_BUDGET_HOLD"] platformAdAccountName: type: [string, "null"] description: | Human-readable advertiser/account name (Meta `AdAccount.name`, TikTok `advertiser_name`, LinkedIn / X / Pinterest equivalents). Refreshed every sync so platform-side renames propagate within one cycle. `null` when the platform doesn't return a name or the sync hasn't run yet. example: "Zernio - previously Late" platformCreatedAt: type: [string, "null"] format: date-time description: | Platform-reported creation timestamp (Meta `created_time`, TikTok `create_time`). Distinct from `createdAt` which reflects when Zernio first synced the doc — for sort/filter by "when the ad was actually created on the platform", read this field. `null` for legacy ads synced before this field was added; aggregations fall back to `createdAt` in that case. bidStrategy: anyOf: - $ref: '#/components/schemas/BidStrategy' - type: "null" description: | Ad-set bid strategy (overrides campaign level on Meta). Populated for Meta and TikTok. TikTok's native `bid_type` is normalized to the cross-platform Meta enum: `BID_TYPE_NO_BID` -> `LOWEST_COST_WITHOUT_CAP`, `BID_TYPE_CUSTOM` -> `LOWEST_COST_WITH_BID_CAP`, deep_bid_type=MIN_ROAS or roas_bid>0 -> `LOWEST_COST_WITH_MIN_ROAS`, `BID_TYPE_MAX_CONVERSION` -> `LOWEST_COST_WITHOUT_CAP`. example: LOWEST_COST_WITHOUT_CAP bidAmount: type: [number, "null"] description: | Bid amount in WHOLE currency units of the ad account (USD: 5 = $5.00; JPY: 100 = ¥100). - Meta source: `bid_amount` on the ad set (smallest-denomination int, decoded here). Populated when bidStrategy is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`; `null` for auto-bid (`LOWEST_COST_WITHOUT_CAP`). - TikTok source: priority order `bid_price` -> `conversion_bid_price` -> `deep_cpa_bid` (whichever is set on the ad group). TikTok stores all three in whole currency units. - LinkedIn source: the campaign's EFFECTIVE `unitCost`, refreshed on every sync rather than echoing what was passed on create. Its meaning depends on the bidding mode implied by `optimizationGoal`: bid amount (manual), target cost, or cost cap. It pairs with `costType`, NOT with `bidStrategy`, which LinkedIn does not have. A value of `0` is a real, delivery- stopping configuration and not "unset", so do not gate this field on `bidStrategy` for LinkedIn ads. Source: facebook-business-sdk-codegen api_specs/specs/AdSet.json (`bid_amount`). example: 5 roasAverageFloor: type: [number, "null"] description: | Minimum ROAS as a decimal multiplier (2.0 = 2.0x ROAS). Populated when bidStrategy is `LOWEST_COST_WITH_MIN_ROAS`. - Meta source: decoded from `bid_constraints.roas_average_floor` (Meta stores as fixed-point int × 10000; we return the decimal). - TikTok source: `roas_bid` on the ad group (already a decimal). Source: facebook-business-sdk-codegen api_specs/specs/AdCampaignBidConstraint.json. example: 2.0 promotedObject: type: [object, "null"] description: "Meta promoted object containing conversion event details. Structure varies by objective. Only present for Meta ads." properties: custom_event_type: { type: string, description: "Conversion event type (e.g. PURCHASE, LEAD, COMPLETE_REGISTRATION, ADD_TO_CART)", example: PURCHASE } pixel_id: { type: string, description: Meta pixel ID } page_id: { type: string, description: Facebook page ID } application_id: { type: string, description: Facebook app ID } product_set_id: { type: string, description: Product catalog set ID } creative: type: [object, "null"] description: Platform-specific creative data. Fields vary by platform. properties: thumbnailUrl: { type: [string, "null"], description: Primary thumbnail/image URL } imageUrl: { type: string, description: Alternative image URL } videoId: { type: [string, "null"], description: "Meta video ID for VIDEO-type ads. Null for non-video ads. Callers that need an embeddable MP4 can call GET /{videoId}?fields=source with the page access token." } videoUrl: { type: [string, "null"], description: "Public Facebook watch URL for VIDEO-type ads (https://www.facebook.com/watch/?v={videoId}). Null for non-video ads." } objectType: { type: string, description: "Meta creative object_type (e.g. SHARE, VIDEO, PRIVACY_CHECK_FAIL, POST_DELETED). Use this to render state-aware previews — when Meta moderation strips image/video fields, only thumbnailUrl at 64x64 is available." } objectStoryId: { type: [string, "null"], description: "Meta creative `object_story_id` (the SHARE reference). Frequently absent — Meta omits it for SHARE creatives. Use effectiveObjectStoryId instead." } effectiveObjectStoryId: { type: [string, "null"], description: "Meta `effective_object_story_id` — `{pageId}_{postId}` of the Facebook post the ad's engagement (comments) lives on. Pass to GET /v1/ads?effectiveObjectStoryId= to map a Business-Manager-visible post back to this ad; GET /v1/ads/{adId}/comments resolves comments against it." } pageId: { type: [string, "null"], description: "Facebook Page backing the creative (Meta only). What the `pageId` filter on /v1/ads, /v1/ads/campaigns and /v1/ads/tree matches against. Absent for non-Meta ads and rare Meta creatives with no page signal." } effectiveInstagramMediaId: { type: [string, "null"], description: "Meta `effective_instagram_media_id` — the Instagram media ID of the boosted post the ad's engagement lives on. Pass to GET /v1/ads?effectiveInstagramMediaId= to map a Business-Manager-visible IG post back to this ad." } instagramUserId: { type: [string, "null"], description: "Meta `instagram_user_id` — the Instagram-scoped business ID that owns the boosted media." } instagramPermalinkUrl: { type: [string, "null"], description: "Meta `instagram_permalink_url` — public Instagram post URL of the boosted media." } mediaUrls: type: array items: { type: string } description: All media URLs for this ad (carousel images, multiple assets). Populated for Meta (carousel child_attachments), Google Ads (responsive display marketing_images), and LinkedIn (multi-image posts). isServing: { type: [boolean, "null"], description: "LinkedIn only. Whether LinkedIn is currently serving this specific creative. Complements the ad-level `servingStatuses`, which describes the parent campaign." } servingHoldReasons: type: array items: { type: string } description: | LinkedIn only. Why this specific creative is not being served. Empty when it is serving. A superset of the ad-level `servingStatuses`: it repeats the inherited campaign, campaign group and account holds AND adds creative-only causes such as UNDER_REVIEW, REJECTED, PROCESSING, PROCESSING_FAILED, FORM_HOLD (lead-gen-form creatives), REFERRED_CONTENT_QUALITY_HOLD, JOB_POSTING_ON_HOLD and JOB_POSTING_INVALID (job ads). Some values are format-specific and will never appear on other ad formats. The list is open, so treat unrecognized values as holds rather than errors. example: ["UNDER_REVIEW"] body: { type: string, description: Ad copy/text } googleHeadline: { type: string, description: Google Ads headline } googleDescription: { type: string, description: Google Ads description } linkUrl: { type: string, description: Destination URL } pinterestImageUrl: { type: string } pinterestTitle: { type: string } pinterestDescription: { type: string } targeting: type: object description: | The ad set's targeting (age, gender, geo, interests, placements, audience inclusions/exclusions). For ads created through Zernio this is the spec you supplied. For external ads (synced from Meta Ads Manager, `isExternal: true`) targeting lives at the ad set and isn't stored at ingest, so on the first `GET /v1/ads/{adId}` Zernio resolves it live from Meta and caches it on the ad; the value is then Meta's raw `targeting` shape (snake_case, e.g. `geo_locations`, `age_min`), the same object Ads Manager shows. May be absent if the ad set exposes no targeting or the lookup fails. schedule: type: [object, "null"] properties: startDate: { type: string, format: date-time } endDate: { type: string, format: date-time } rejectionReason: { type: string } createdAt: { type: string, format: date-time } updatedAt: { type: string, format: date-time } AdTreeAdSet: type: object description: Ad set (or ad group/line item depending on platform) with rolled-up metrics and child ads properties: platformAdSetId: { type: string } adSetName: { type: string } status: { allOf: [{ $ref: '#/components/schemas/AdStatus' }], description: Derived from child ad statuses } adCount: { type: integer } budget: type: [object, "null"] description: Effective budget at this level (back-compat). For CBO campaigns this mirrors the parent campaign's budget; for ABO this is the ad-set-specific budget. Use `adSetBudget` / parent `campaignBudget` + `budgetLevel` to disambiguate. properties: amount: { type: number } type: { type: string, enum: [daily, lifetime] } adSetBudget: type: [object, "null"] description: Ad-set-level budget (ABO). Null for CBO campaigns where the budget is set on the campaign. properties: amount: { type: number } type: { type: string, enum: [daily, lifetime] } metrics: { $ref: '#/components/schemas/AdMetrics' } optimizationGoal: { type: [string, "null"], description: "What the delivery system optimizes for. Meta ad set optimization goal (e.g. OFFSITE_CONVERSIONS, VALUE, LEAD_GENERATION), or on LinkedIn the campaign's effective optimizationTargetType (NONE means manual bidding). See the `optimizationGoal` field on `Ad` for the full value spaces." } bidStrategy: anyOf: - $ref: '#/components/schemas/BidStrategy' - type: "null" description: "Bid strategy for this ad set (overrides campaign level when set). Meta and TikTok only; LinkedIn uses `costType` instead." bidAmount: { type: [number, "null"], description: "Bid amount in whole currency units. On Meta/TikTok populated when bidStrategy is LOWEST_COST_WITH_BID_CAP or COST_CAP; on LinkedIn it is the campaign's effective unitCost and pairs with `costType`, where 0 is a real, delivery-stopping value." } roasAverageFloor: { type: [number, "null"], description: "Minimum ROAS as a decimal multiplier (2.0 = 2.0x). Populated when bidStrategy is LOWEST_COST_WITH_MIN_ROAS." } costType: { type: [string, "null"], description: "LinkedIn only. Effective cost model (billing event) of the LinkedIn campaign backing this ad set: CPM, CPC or CPV. Null for non-LinkedIn ad sets." } servingStatuses: type: array items: { type: string } description: "LinkedIn only. Why the LinkedIn campaign backing this ad set is (or is not) delivering. A LinkedIn Campaign maps to this ad-set node, so this is the level where LinkedIn's holds actually apply. Empty means no serving data, [\"RUNNABLE\"] means eligible to serve, anything else is a hold. See the `servingStatuses` field on `Ad` for the known values." example: ["RUNNABLE"] promotedObject: type: [object, "null"] description: "Meta promoted object for this ad set (conversion event details)" properties: custom_event_type: { type: string } pixel_id: { type: string } page_id: { type: string } ads: type: array items: { $ref: '#/components/schemas/Ad' } description: "Individual ads within this ad set (capped at 100). Returns a subset of Ad fields from the aggregation: `_id`, `name`, `platform`, `status`, `configuredStatus`, `reviewStatus`, `budget`, `metrics`, `creative`, `goal` and the `platform*` ids are always included; `targeting` and `schedule` may be absent. `configuredStatus` (the ad's own on/off toggle) and `reviewStatus` (the platform's review verdict) are part of this contract, not incidental: a rejected ad is only distinguishable from a healthy one through `reviewStatus`. When `timeIncrement=1&dailyLevel=ad`, each entry also carries a `daily[]` array of `AdDailyMetrics`." daily: type: array items: { $ref: '#/components/schemas/AdDailyMetrics' } description: "Per-day metric series for this ad set. Present only when `GET /v1/ads/tree` is called with `timeIncrement=1` and `dailyLevel` is `adset` or `ad`." AdTreeCampaign: type: object description: Campaign with nested ad sets and rolled-up metrics properties: platformCampaignId: { type: string } platform: { type: string, enum: [facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai] } campaignName: { type: string } status: { allOf: [{ $ref: '#/components/schemas/AdStatus' }], description: "Delivery status derived from child ad statuses. Distinct from `reviewStatus`, which reflects the platform-side review state." } reviewStatus: anyOf: - $ref: '#/components/schemas/AdReviewStatus' - type: "null" description: | Platform-side review state of the campaign. Independent of the children-derived delivery `status`: a campaign can have ads already active (status=active) while the campaign itself is still being reviewed by the platform (reviewStatus=in_review). For Meta, derived from `effective_status` + `issues_info` on the Campaign, plus ad-level PENDING_REVIEW rollup. platformCampaignStatus: type: [string, "null"] description: "Raw platform-level campaign status (Meta `effective_status`: ACTIVE, PAUSED, DELETED, ARCHIVED, IN_PROCESS, WITH_ISSUES). Distinct from per-ad `platformStatus`." campaignIssuesInfo: type: [array, "null"] description: "Platform-reported campaign issues (Meta `issues_info[]`). Populated only when the platform has delivery issues to report; contains the specific error codes and messages." items: type: object adCount: { type: integer, description: Total ads across all ad sets } adSetCount: { type: integer } budget: type: [object, "null"] description: Effective budget (back-compat). For CBO this mirrors `campaignBudget`, for ABO this mirrors the child ad-set budget. Use `budgetLevel` to disambiguate. properties: amount: { type: number } type: { type: string, enum: [daily, lifetime] } campaignBudget: type: [object, "null"] description: Campaign-level budget (Campaign Budget Optimization / CBO). Populated only when the platform set the budget at the campaign level. For ABO campaigns this is null and the budget lives on the child ad set. properties: amount: { type: number } type: { type: string, enum: [daily, lifetime] } budgetLevel: type: [string, "null"] enum: [campaign, adset] description: "Canonical CBO/ABO indicator. `campaign` = CBO (Advantage Campaign Budget, budget lives on the campaign). `adset` = ABO (budget lives on each ad set). Route budget updates to the matching Meta entity." isBudgetScheduleEnabled: type: boolean default: false description: "Meta-only. Mirrors Campaign.is_budget_schedule_enabled — true when the campaign uses budget scheduling (time-based budget changes). Independent of CBO/ABO." currency: type: [string, "null"] description: "ISO 4217 currency code (e.g. USD, EUR, CLP, JPY) for all budget amounts in this campaign node. Budgets are NOT normalized to USD." metrics: { $ref: '#/components/schemas/AdMetrics' } platformAdAccountId: { type: string } platformAdAccountName: { type: [string, "null"], description: "Human-readable advertiser/account name from the platform. Refreshed on every sync." } accountId: { type: string } profileId: { type: string } advertisingChannelType: type: [string, "null"] description: "Google-only. Raw campaign.advertising_channel_type (SEARCH, PERFORMANCE_MAX, VIDEO, DEMAND_GEN, DISPLAY, SHOPPING, ...). Serving surface, distinct from platformObjective (advertiser intent). Null/absent for non-Google platforms." platformObjective: { type: [string, "null"], description: "Raw Meta campaign objective (e.g. OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_TRAFFIC)" } optimizationGoal: type: [string, "null"] description: "Optimization goal shared across ad sets, or comma-separated values when ad sets differ. Meta: e.g. OFFSITE_CONVERSIONS, VALUE, LEAD_GENERATION. LinkedIn: the campaign optimizationTargetType (e.g. MAX_CLICK, MAX_IMPRESSION, NONE); `NONE` with a manual costType is a campaign LinkedIn will not deliver." bidStrategy: anyOf: - $ref: '#/components/schemas/BidStrategy' - type: "null" description: "Campaign-level bid strategy. Ad sets inherit this unless they override." bidAmount: { type: [number, "null"], description: "Representative bid for the campaign, bubbled up from the top-spending ad set (whole currency units). Meta: populated when the ad-set bidStrategy is LOWEST_COST_WITH_BID_CAP or COST_CAP. LinkedIn: the campaign unitCost, which has no bidStrategy gate and where 0 is a real, delivery-stopping value rather than unset." } roasAverageFloor: { type: [number, "null"], description: "Representative ROAS floor for the campaign — bubbled up from the top-spending ad set. Decimal multiplier (2.0 = 2.0x)." } promotedObject: type: [object, "null"] description: "Meta promoted object at campaign level (conversion event details)" properties: custom_event_type: { type: string } pixel_id: { type: string } page_id: { type: string } adSets: type: array items: { $ref: '#/components/schemas/AdTreeAdSet' } daily: type: array items: { $ref: '#/components/schemas/AdDailyMetrics' } description: "Per-day metric series for this campaign. Present only when `GET /v1/ads/tree` is called with `timeIncrement=1` (any `dailyLevel`). This is the per-campaign daily trend — summing its additive fields reproduces the campaign `metrics` total, except `reach`: on Meta the range total is de-duplicated, so daily reach does not sum to it." AdCampaign: type: object properties: platformCampaignId: { type: string } platform: { type: string, enum: [facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai] } campaignName: { type: string } status: { allOf: [{ $ref: '#/components/schemas/AdStatus' }], description: "Delivery status derived from child ad statuses. Distinct from `reviewStatus`." } reviewStatus: anyOf: - $ref: '#/components/schemas/AdReviewStatus' - type: "null" description: "Platform-side review state of the campaign. See AdTreeCampaign.reviewStatus for the full description." platformCampaignStatus: type: [string, "null"] description: "Raw platform-level campaign status (Meta `effective_status`)." campaignIssuesInfo: type: [array, "null"] description: "Platform-reported campaign issues (Meta `issues_info[]`)." items: type: object adCount: { type: integer } budget: type: [object, "null"] description: Effective budget (back-compat). Use `budgetLevel` to disambiguate CBO vs ABO. properties: amount: { type: number } type: { type: string, enum: [daily, lifetime] } campaignBudget: type: [object, "null"] description: Campaign-level budget (CBO). Null for ABO campaigns. properties: amount: { type: number } type: { type: string, enum: [daily, lifetime] } budgetLevel: type: [string, "null"] enum: [campaign, adset] description: "Canonical CBO/ABO indicator. See AdTreeCampaign.budgetLevel." isBudgetScheduleEnabled: type: boolean default: false description: "Meta-only. Mirrors Campaign.is_budget_schedule_enabled." currency: type: [string, "null"] description: "ISO 4217 currency code for all budget amounts. Budgets are NOT normalized to USD." metrics: { $ref: '#/components/schemas/AdMetrics' } platformAdAccountId: { type: string } platformAdAccountName: { type: [string, "null"], description: "Human-readable advertiser/account name from the platform. Refreshed on every sync." } accountId: { type: string } profileId: { type: string } advertisingChannelType: type: [string, "null"] description: "Google-only. Raw campaign.advertising_channel_type. See AdTreeCampaign.advertisingChannelType." platformObjective: { type: [string, "null"], description: "Raw Meta campaign objective (e.g. OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_TRAFFIC)" } optimizationGoal: type: [string, "null"] description: "Optimization goal shared across ad sets, or comma-separated values when ad sets differ. Meta: e.g. OFFSITE_CONVERSIONS, VALUE, LEAD_GENERATION. LinkedIn: the campaign optimizationTargetType (e.g. MAX_CLICK, MAX_IMPRESSION, NONE); `NONE` with a manual costType is a campaign LinkedIn will not deliver." bidStrategy: anyOf: - $ref: '#/components/schemas/BidStrategy' - type: "null" description: "Campaign-level bid strategy. Ad sets inherit this unless they override." bidAmount: { type: [number, "null"], description: "Representative bid from the top-spending ad set (whole currency units). Meta: populated when bidStrategy is LOWEST_COST_WITH_BID_CAP or COST_CAP. LinkedIn: the campaign unitCost, ungated, where 0 is a real delivery-stopping value." } roasAverageFloor: { type: [number, "null"], description: "Representative ROAS floor from the top-spending ad set. Decimal multiplier (2.0 = 2.0x)." } promotedObject: type: [object, "null"] description: "Meta promoted object at campaign level (conversion event details)" properties: custom_event_type: { type: string } pixel_id: { type: string } page_id: { type: string } earliestAd: { type: string, format: date-time } latestAd: { type: string, format: date-time } ConversionEvent: type: object description: | A single conversion event to relay to the ad platform. All PII fields (email, phone, names) are hashed with SHA-256 server-side using each platform's normalization rules before they leave Zernio. Callers send plaintext. required: [eventName, eventTime, eventId, user] properties: eventName: type: string description: | Standard event name (Purchase, Lead, CompleteRegistration, AddToCart, InitiateCheckout, AddPaymentInfo, Subscribe, StartTrial, ViewContent, Search, Contact, SubmitApplication, Schedule) or a custom string (only supported on platforms that accept custom events — Meta and OpenAI Ads). Per-platform behavior: - Meta: free-form; standard names match Meta's built-ins. - Google: ignored — the conversion action's category determines the type. - LinkedIn: ignored — the conversion rule's `type` is locked to the destination. - OpenAI Ads: a fixed subset of standard names (Purchase, Lead, AddToCart, ViewContent, InitiateCheckout, CompleteRegistration, Subscribe, StartTrial, Schedule) maps 1:1 onto OpenAI's own event-type enum; anything else is sent as a custom event with the name preserved. example: Purchase eventTime: type: integer description: When the conversion happened, in unix seconds. example: 1744732800 eventId: type: string description: | Unique dedup key. The same eventId must be used on pixel + CAPI to prevent double-counting. Mapped to event_id on Meta, transactionId on Google, eventId on LinkedIn (LinkedIn deduplicates against Insight Tag events with the same eventId; the Insight Tag event wins when both arrive). example: order_abc_123 value: type: number description: Conversion value in the specified currency. example: 99.5 currency: type: string description: ISO 4217 currency code. example: USD user: type: object description: User identity fields. More signals mean higher match rates. properties: email: { type: string, description: Plaintext email. Hashed server-side. } phone: { type: string, description: "Phone number, ideally E.164. Hashed server-side." } firstName: { type: string, description: Plaintext first name. Hashed server-side. } lastName: { type: string, description: Plaintext last name. Hashed server-side. } externalId: type: string description: | Stable customer identifier (e.g. CRM user ID). Hashed server-side for Meta and Google. Sent as plaintext to LinkedIn (LinkedIn's Conversions API spec requires the raw value). Maximum effective list size on LinkedIn is 1. ipAddress: { type: string, description: Client IP address. Sent plaintext. } userAgent: { type: string, description: Client user-agent string. Sent plaintext. } country: { type: string, description: "ISO 3166-1 alpha-2 country code, e.g. 'us'." } city: { type: string, description: "Meta advanced matching (ct). Plaintext city; normalized + SHA-256 hashed server-side. Meta only." } state: { type: string, description: "Meta advanced matching (st). 2-letter ANSI for US; hashed server-side. Meta only." } zip: { type: string, description: "Meta advanced matching (zp). US uses first 5 digits; hashed server-side. Meta only." } dob: { type: string, description: "Meta advanced matching (db). YYYYMMDD; hashed server-side. Meta only." } gender: { type: string, description: "Meta advanced matching (ge). 'f' or 'm'; hashed server-side. Meta only." } leadId: type: string description: | Meta lead ID from a Lead Ad submission, as a string. Required for Conversion Leads CRM events: send it with `actionSource: 'crm'` and `platformData: { event_source: 'crm', lead_event_source: '' }`. Forwarded unhashed to Meta's `user_data.lead_id`. Meta only. clickIds: type: object description: Platform click identifiers captured from the originating ad click. properties: fbc: { type: string, description: Meta click ID (from fbclid URL param). } fbp: { type: string, description: Meta browser ID (_fbp cookie). } gclid: { type: string, description: Google click ID (from gclid URL param). } gbraid: { type: string, description: Google iOS 14.5+ app attribution ID. } wbraid: { type: string, description: Google iOS 14.5+ web-to-app attribution ID. } li_fat_id: type: string description: | LinkedIn first-party ad tracking click ID. Captured by parsing `li_fat_id` from landing-page URLs after the advertiser enables enhanced conversion tracking on the LinkedIn Insight Tag. Sent to LinkedIn as the LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID userId. Opaque token, not hashed. items: type: array description: Item-level detail for ecommerce events. items: type: object properties: id: { type: string } name: { type: string } price: { type: number } quantity: { type: integer } category: { type: string } sourceUrl: type: string format: uri description: URL where the conversion originated (used by Meta). actionSource: type: string enum: [web, app, offline, crm, phone_call, system_generated] description: 'Where the conversion happened. Used by Meta. Google also requires an event source internally; omitting this field sends OTHER to Google. Send an explicit value for accurate origin reporting.' platformData: type: object additionalProperties: true description: | Escape hatch for platform-specific fields we haven't normalized. On Meta, keys are shallow-merged into `custom_data` only: fields Zernio already builds (`value`, `currency`, `contents`, `num_items`) always win on collision, and `user_data` (hashed match keys) is never touched. Use first-class fields (e.g. `user.leadId`) for anything that must reach `user_data`. ConversionDestination: type: object description: | A discoverable conversion destination on an ad platform — a Meta pixel, Google conversion action, or LinkedIn conversion rule. Returned by `listConversionDestinations`, `getConversionDestination`, `createConversionDestination`, and `updateConversionDestination`. required: [id, name] properties: id: type: string description: | Platform-native identifier. Pass back as `destinationId` on event send and as the path segment on CRUD endpoints. name: { type: string } type: type: string description: | Present when the platform locks the event type/category to the destination (Google conversion actions, LinkedIn conversion rules). Absent for Meta pixels (which accept any event name per request). status: type: string enum: [active, inactive] description: | For LinkedIn, `inactive` means the rule is soft-deleted (`enabled: false`). adAccountId: type: string description: | Set by adapters whose destinations are scoped to a specific ad account (LinkedIn). Pass back on subsequent CRUD calls to identify the parent ad account. CtwaSingleResponse: type: object description: | Response returned by `POST /v1/ads/ctwa` when the request used the single-creative shape (top-level headline / body / imageUrl|video). `adType` is the union discriminator. required: [adType, ad, message] properties: adType: { type: string, enum: [single] } ad: { type: object, description: The persisted Ad document. } message: { type: string } CtwaMultiResponse: type: object description: | Response returned by `POST /v1/ads/ctwa` when the request used the multi-creative shape (`creatives[]`). N persisted Ad documents share the returned `platformCampaignId` and `platformAdSetId`. `adType` is the union discriminator. required: [adType, ads, platformCampaignId, platformAdSetId, message] properties: adType: { type: string, enum: [multi] } ads: type: array description: | The persisted Ad documents (one per creative), all sharing the same `platformCampaignId` and `platformAdSetId`. items: { type: object } platformCampaignId: { type: string } platformAdSetId: { type: string } message: { type: string } TrackingTag: type: object description: | A platform measurement tag — the thing you create, install on a website, send events to, and target ads against. On Meta this is a Pixel (`kind: pixel`). The shape is platform-neutral so other platforms (Pinterest Tag, LinkedIn Insight Tag, etc.) can be added without changing the contract; platform-specific fields are simply absent where a platform has no equivalent. Returned by `listTrackingTags`, `createTrackingTag`, `getTrackingTag`, and `updateTrackingTag`. required: [id, name, platform, kind, status] properties: id: type: string description: 'Platform-native tag id. Meta: numeric pixel id, as a string.' name: { type: string } platform: { type: string, enum: [metaads] } kind: type: string enum: [pixel, tag, insight_tag] description: 'Platform-native flavor of the tag (Meta: `pixel`).' status: type: string enum: [active, inactive] description: '`inactive` when the platform reports the tag as broken/unavailable.' code: type: string description: | The base-code `