late 0.0.1336

API reference for Zernio. Authenticate with a Bearer API key. Base URL: https://zernio.com/api Versioning and deprecation: all endpoints are versioned in the URL path (current version: /v1). Breaking changes only ship in a new path version; existing versions keep working. Deprecated operations are marked 'deprecated: true' in this spec and announced in the changelog (https://zernio.com/changelog) before removal. Errors: every 4xx/5xx response is application/json with a machine-readable 'code' and a human-readable 'error' message (see the ErrorResponse schema). Request ids: responses carry an X-Request-Id header with the id we log the request under. Quote it when reporting a problem. A valid x-request-id you send is reused as that id.
Documentation
1
{"openapi":"3.1.0","info":{"title":"Zernio API","version":"1.517.0","description":"API reference for Zernio. Authenticate with a Bearer API key.\nBase URL: https://zernio.com/api\n\nVersioning and deprecation: all endpoints are versioned in the URL path\n(current version: /v1). Breaking changes only ship in a new path version;\nexisting versions keep working. Deprecated operations are marked\n'deprecated: true' in this spec and announced in the changelog\n(https://zernio.com/changelog) before removal.\n\nErrors: every 4xx/5xx response is application/json with a machine-readable\n'code' and a human-readable 'error' message (see the ErrorResponse schema).\n\nRequest ids: responses carry an X-Request-Id header with the id we log the\nrequest under. Quote it when reporting a problem. A valid x-request-id you\nsend is reused as that id.\n","termsOfService":"https://zernio.com/tos","contact":{"name":"Zernio Support","url":"https://zernio.com","email":"support@zernio.com"},"x-logo":{"url":"https://zernio.com/icon.png?v=3"},"x-long-description":"Zernio is the social media API that replaces 29 integrations. Schedule posts, retrieve analytics,\nmanage DMs, comments, and reviews across X, Instagram, WhatsApp, TikTok, LinkedIn,\nFacebook, YouTube, Threads, Pinterest, Bluesky, Telegram, Google Business Profile, Snapchat,\nDiscord, Slack, and iMessage, all from a single REST API. Run paid ads on Meta (Facebook + Instagram), Google,\nTikTok, LinkedIn, Pinterest, X, OpenAI, Reddit, and Microsoft from the same account.\n\nConnect Shopify, WordPress and Wix as blog accounts to list sites and manage\narticles, drafts, featured images, tags, authors, and native scheduling.\n\nKey features: Unified posting to 16 platforms, ads management on 9 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.\n\nSupported posting platforms: X, Instagram, WhatsApp, Facebook, LinkedIn, TikTok, YouTube, Pinterest, Bluesky, Threads, Google Business Profile, Telegram, Snapchat, Discord, Slack. Supported ad platforms: Meta Ads, Google Ads, TikTok Ads, LinkedIn Ads, Pinterest Ads, X Ads, OpenAI Ads, Reddit Ads, Microsoft Ads. Snapchat is a closed beta with no public release date: connections are gated behind approval and return 403 `PLATFORM_BETA_RESTRICTED` until then. Organic Reddit is temporarily unavailable: Reddit has blocked third-party apps from its API, so Reddit posting, messages, analytics and the Reddit endpoints return 503 `PLATFORM_DISABLED` until Reddit restores access. Your Reddit accounts stay connected. Reddit Ads is not affected.\n","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"}]},"x-documentation":{"readme":"# Zernio API\n\nThe social media API that replaces 29 integrations. Build social media and blog publishing features into your app in minutes, not months.\n\n## Quick Start\n\n**Base URL:** `https://zernio.com/api/v1`\n\n**Authentication:** All requests require a Bearer API key in the `Authorization` header.\n\n```bash\ncurl https://zernio.com/api/v1/user \\\n  -H \"Authorization: Bearer YOUR_API_KEY\"\n```\n\nGet your API key at [zernio.com/dashboard/api-keys](https://zernio.com/dashboard/api-keys).\n\n## Core Concepts\n\n| Concept | Description |\n|---------|-------------|\n| **Profiles** | Containers that organize accounts into brands or projects |\n| **Accounts** | Connected social, ads, commerce, and blog accounts belonging to a profile |\n| **Posts** | Content scheduled or published to one or more accounts |\n| **Blogs** | Articles managed on connected Shopify and WordPress sites |\n| **Queue** | Recurring time slots for automatic post scheduling |\n\n## Create a Post\n\n```bash\ncurl -X POST https://zernio.com/api/v1/posts \\\n  -H \"Authorization: Bearer $ZERNIO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"content\": \"Hello from the Zernio API.\",\n    \"scheduledFor\": \"2027-01-15T10:00:00Z\",\n    \"platforms\": [\n      { \"platform\": \"twitter\", \"accountId\": \"64e1f0a9e2b5af0012ab34cd\" },\n      { \"platform\": \"linkedin\", \"accountId\": \"66b2e19d8c3f5a7e9d0b1c2d\" }\n    ]\n  }'\n```\n\nThis single call publishes or schedules the post to every account in `platforms`, across any platform. Send `publishNow: true` instead of `scheduledFor` to publish immediately.\n\n## Supported Platforms\n\n| Platform | Post | Stories/Reels | Analytics | Inbox |\n|----------|------|---------------|-----------|-------|\n| X | Yes | - | Yes | Yes |\n| Instagram | Yes | Yes | Yes | Yes |\n| Facebook | Yes | Stories | Yes | Yes |\n| LinkedIn | Yes | - | Partial | - |\n| TikTok | Yes | - | Yes | Comments |\n| YouTube | Yes | Shorts | Yes | Yes |\n| Pinterest | Yes | - | Yes | - |\n| Reddit (temporarily unavailable) | - | - | - | - |\n| Bluesky | Yes | - | Partial | Yes |\n| Threads | Yes | - | Yes | Yes |\n| Google Business Profile | Yes | - | - | Yes |\n| Telegram | Yes | - | - | - |\n| Snapchat | Yes | - | - | - |\n\n> **Snapchat Note:** Snapchat is a closed beta with no public release date. Connecting a Snapchat account is gated behind approval and returns 403 `PLATFORM_BETA_RESTRICTED` until then.\n\n> **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.\n\n> **Google Business Profile Analytics Note:** Per-post analytics for Google Business Profile are deprecated by Google with no replacement, so Google Business Profile 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.\n\n> **TikTok Inbox Note:** Comment management (read, reply, hide, pin, like, delete) needs an account connected through the TikTok for Business app, which is what every new TikTok connection now uses. It does not require the TikTok account itself to be a Business Account. An account connected earlier through the TikTok developer app returns 400 `PLATFORM_LIMITATION` on the comment routes until it is reconnected. TikTok direct messages are not generally available: on top of the same connection they need a real TikTok Business Account whose sign-up region is outside the EEA, Switzerland and the UK, plus TikTok messaging approval for the calling app, and TikTok reports every one of those as a misleading \"access token is invalid\". Do not treat that as an expired token.\n\n## Rate Limits\n\nAPI request throughput is rate-limited per minute on a sliding window. Limits scale with your team's total connected accounts:\n\n- **0 to 2 accounts** (free tier): 60 req/min\n- **3 to 2,000 accounts**: 600 req/min\n- **2,001+ accounts**: 1,200 req/min\n\nLegacy AppSumo lifetime tiers get a flat 600 req/min regardless of tier.\n\nReads that integrations tend to poll have an extra cap of 1,800 requests per hour per team, on a sliding window, counted separately for each group: inbox comments (`GET /v1/inbox/comments` and `GET /v1/inbox/comments/{postId}`), ad comments (`GET /v1/ads/{adId}/comments`) and Google Business reviews (`GET /v1/accounts/{accountId}/gmb-reviews` and `POST /v1/accounts/{accountId}/gmb-reviews/batch`). Past it the API answers 429 with `details.scope` naming the group. Subscribe to the `comment.received`, `review.new` and `review.updated` webhooks instead of polling these routes.\n\nAnalytics reads made with an API key have a cap per team on a 30-second sliding window, on top of the limits above and counted separately for each group: 120 requests for campaign analytics (`GET /v1/ads/campaigns/{campaignId}/analytics`), 300 for ad analytics (`GET /v1/ads/{adId}/analytics`), 150 for ads listings (`GET /v1/ads`, `/v1/ads/tree`, `/v1/ads/timeline`, `/v1/ads/campaigns`, `/v1/ads/performance` and `/v1/ads/alerts`) and 300 for post and inbox analytics (the `/v1/analytics` routes that read stored metrics; the live platform routes such as `/v1/analytics/instagram/*` are not included). Past a cap the API answers 429 with `Retry-After`, `details.scope` naming the group and `details.window`. Read many ads or campaigns in one request with `GET /v1/ads/tree` instead of one request each. Requests from the Zernio dashboard do not count.\n\nPosts themselves are unlimited on every connected 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, Google Business 100/day, Threads 250/day, X 50/day plus 200 replies for unverified accounts and 2,400 posts a day for verified X accounts, Pinterest 25/day, 50/day for every other platform), plus a 25-posts-per-hour per-account velocity cap.\n\nTikTok caps accounts connected through the TikTok for Business app lower than any of those: 15 videos and 15 photo posts per account per day, counted separately. Zernio enforces it as a trailing 24 hour window rather than a calendar day, and a post over the cap is not rejected. It is held and published automatically once the oldest post of the same kind leaves the window, so `scheduledFor` on that platform entry moves to the time it will go out.\n\nAll responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers, describing whichever limit that applies to the request has the fewest requests left. Read these instead of hard-coding limits, since your tier may be configured higher than the default.\n\n## Webhooks\n\nReceive real-time notifications for post status changes, account events, and incoming messages:\n\n- `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\n- `post.published` - Post successfully published. If a platform target later fails background reconciliation, the post is re-rolled up and a `post.failed` or `post.partial` follows for the same post.\n- `post.failed` - Post failed on all platforms. Can follow an earlier `post.published` for the same post when background reconciliation discovers the publish never actually completed.\n- `post.partial` - Post published to some platforms, failed on others. Can follow an earlier `post.published` for the same post when background reconciliation discovers one target's publish never actually completed.\n- `post.cancelled` - A scheduled post was cancelled because its account was disconnected (not sent by `DELETE /v1/posts/{postId}`)\n- `post.recycled` - Post recycled (cloned and re-scheduled)\n- `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. A target that later fails background reconciliation (e.g. a Facebook video Meta accepted but never actually published) emits `post.platform.failed` afterward for the same target.\n- `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. Can fire after this same target already emitted `post.platform.published`, when background reconciliation later discovers the publish never actually completed on the platform's side.\n- `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.\n- `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.\n- `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\"`.\n- `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.\n- `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, and detection is a diff against posts a prior sync already indexed, so an account for which no post has ever been indexed never emits it.\n- `account.connected` - Account connected\n- `account.disconnected` - Account disconnected: deactivated after its token was revoked or rejected (or the platform refused it, e.g. a Facebook Page left out of a later authorization), or flagged as needing reconnection. Not sent again while the account stays deactivated\n- `account.permissions_changed` - An account connected through your own OAuth app lost a permission area (for example posting) while staying connected\n- `account.rate_limited` - A Google or Microsoft mailbox entered a sending cooldown; sends answer 429 until `account.resetsAt`\n- `account.ads.initial_sync_completed` - Initial ads sync (discovery + 90-day backfill) completed for an ads-enabled account\n- `account.ads.sync_failed` - An ad account's ads stopped syncing (no successful sync for 24 hours, or every live ad at the retry cap). Fires once until it recovers\n- `account.ads.sync_recovered` - An ad account reported by `account.ads.sync_failed` is syncing again\n- `calendar.event.created` / `calendar.event.updated` / `calendar.event.deleted` - An event changed on a connected Microsoft calendar (push). Carries the event id and the change; read it with `GET /v1/calendar/events/{id}`\n- `analytics.synced` - One connected account's analytics sync cycle finished. A trigger, not a transport: it carries no metrics and no cursor, so call `GET /v1/analytics/delta` with your own last `nextCursor` to read what changed across every account. Poll-driven (~hourly per account), not real-time. High volume: subscribe to it on a dedicated endpoint.\n- `post.tracking_completed` - A post's tracking window ended and its final analytics read finished. Carries the closing metrics (or `final: null` when none could be read) and why the window completed: `final_read`, `unreachable` or `post_deleted`\n- `post.authenticity_changed` - A tracked post's authenticity score crossed the flag threshold of 40, in either direction. Carries the new and previous score, confidence and reasons. A post's first score never fires it\n- `message.received` - New inbound DM or SMS received (SMS arrives with `platform: \"sms\"`)\n- `conversation.started` - A new conversation opened between one of your accounts and a contact, in either direction (any DM platform, and SMS); fires only the first time the thread appears\n- `conversation.control_changed` - Meta's handover protocol moved a conversation. WhatsApp: Meta Business Agent took it over or handed it to you; while `control.owner` is `ai_agent`, inbound messages arrive with `metadata.standby: true` and the agent answers them, and sending a message takes control back. Facebook and Instagram: another app (such as Page Inbox) passed or took the thread; while you are not the owner, inbound arrive with `metadata.standby: true` and sends fail with `not_thread_owner` until you take control with thread-control (accounts connected through a Facebook Page; an Instagram Login connection cannot take and waits for the owner to pass it)\n- `message.sent` - DM sent via the API. `message.sentVia` says which Zernio surface produced it, and `automationId`, `workflowId` / `executionId`, `broadcastId` or `sequenceId` name the automation, workflow run, broadcast or sequence that sent it\n- `message.edited` - A sender edited a message (Instagram, Messenger, Telegram, WhatsApp)\n- `message.deleted` - A sender deleted (\"unsent\") a message (Instagram; WhatsApp in both directions, whether the business deleted a message it sent or the customer deleted one they sent). `message.direction` tells the two apart.\n- `message.delivered` - An outgoing message was delivered (WhatsApp, Messenger, SMS, RCS)\n- `message.read` - An outgoing message was read by the recipient (WhatsApp, Messenger, Instagram, RCS)\n- `message.failed` - An outgoing message failed delivery (WhatsApp, SMS, RCS; on SMS the carrier's error code rides in `error`)\n- `reaction.received` - A participant added or removed an emoji reaction on a message (WhatsApp, Telegram, Slack, Instagram, Facebook Messenger, TikTok)\n- `referral.received` - Someone opened an existing Instagram/Messenger thread through an ig.me/m.me `ref` link or a returning Messenger ad click; carries Meta's referral object (a referral that rides an inbound message arrives on `message.received` under `metadata.referral` instead)\n- `comment.received` - New comment received on a post (Instagram, Facebook, Threads, YouTube, LinkedIn, Bluesky, Reddit, TikTok). X/Twitter does NOT fire this event\n- `review.new` - New review posted on a connected account (Google Business Profile)\n- `review.updated` - A Google Business Profile reviewer edited their review text or rating, or a reply was added, edited or removed. A reply posted through `POST /v1/inbox/reviews/{reviewId}/reply` fires immediately, and the periodic check reports it again with the full review payload, so expect a second delivery. A reply removed through the API, or written or removed in Google's own interface, is reported by the periodic check: for replies written in Google, usually within 6 hours for reviews updated in the last 30 days and usually within about 7 days for older ones. Only teams with a webhook subscribed to `review.updated` are checked. A removed reply fires with `hasReply: false`.\n- `review.deleted` - Google Business Profile stopped returning this review, for example after Google's spam filter removed it. Detected by polling: fires usually 6 to 12 hours after the review disappears, only for locations covered by a webhook subscribed to `review.deleted` or `review.restored`. If the review comes back, `review.restored` fires. May arrive for a review id you never received `review.new` for. A review hidden and restored by Google may produce `review.deleted` followed by `review.restored`, and a `review.updated` can arrive for a review previously reported by `review.deleted` (it is restored on the next check).\n- `review.restored` - A review reported by `review.deleted` is returned by Google again. Same payload as `review.new`.\n- `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.\n- `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)\n- `ad.created` - An ad was created through Zernio (`source` is `zernio`) or detected by the sync (`source` is `platform`). Never for history loaded when an account connects, nor for ads older than 7 days\n- `ad.updated` - An ad was edited through Zernio (API, MCP or dashboard) or outside it. `changes` lists the edited fields. `source` is `zernio` for edits through Zernio, `platform` for edits the sync detected outside Zernio, up to one sync interval late. From the sync, `changes` covers only `name` and `status`. Budget, bid, schedule and targeting edits made outside Zernio are not announced on the ad. Never for history loaded when an account connects\n- `campaign.created` - A campaign was created through Zernio (`source` is `zernio`) or detected by the sync (`source` is `platform`). Never for history loaded when an account connects, nor for campaigns older than 7 days\n- `campaign.updated` - A campaign was edited through Zernio (API, MCP or dashboard) or outside it. `changes` lists the edited fields. `source` is `zernio` for edits through Zernio, `platform` for edits the sync detected outside Zernio, up to one sync interval late. From the sync, `changes` covers only `name`, `status` and `schedule` (schedule only on Google, LinkedIn, Pinterest and OpenAI Ads), sent only to the user whose sync saw it. Budget edits made outside Zernio are not announced. Never for history loaded when an account connects\n- `ad.review.approved` - An ad Zernio already tracked passed platform review, or a rejection was overturned (every ad network)\n- `ad.review.rejected` - An ad Zernio already tracked was rejected in platform review (every ad network). `review.reasons` carries the platform's reason when it gives one\n- `ad.delivery_issue` - An ad Zernio already tracked stopped delivering for a platform reason (Meta `WITH_ISSUES`, TikTok account or balance problems). `issue.reasons` carries Meta's messages\n- `campaign.budget.depleted` - A campaign Zernio already tracked ran out of budget (TikTok, the only network that reports it on the ad)\n- `ad_account.status_changed` - An ad account Zernio already tracked became `active`, `restricted`, `disabled` or `closed` (Meta, Google, TikTok, X)\n- `ad.video.processed` - Meta finished processing a video uploaded with `POST /v1/ads/videos` and `async: true`. `video.status` is `ready` (usable as `video.id`) or `error`\n- `ad_rule.triggered` - A scheduled ad rule run found campaigns, ad sets or ads meeting every condition, once per object per cooldown. `objects` lists the objects acted on\n- `automation.check.completed` - One scheduled check of an automation finished (ad rules today): its outcome, how many objects it read and how many actions it took\n- `automation.action.applied`, `automation.action.failed`, `automation.action.unknown` - One change an automation made or tried, with the value before and the value it sets (`previous`, `target`). Refusals arrive as `failed` with status `skipped`; `unknown` means the platform did not answer and the next check reads the result back\n- `automation.alert.opened`, `automation.alert.escalated`, `automation.alert.resolved` - An alert episode of an automation with a lifecycle: confirmed and acted on, turned critical, or ended (`reason` says why)\n- `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\".\n- `whatsapp.template.category_updated` - Meta reclassified a WhatsApp Business template's category (drives tariff and marketing opt-out applicability). `template.changeType` is `scheduled` (24h advance notice) or `applied`; `template.category` is always the category right now.\n- `whatsapp.account.name_status_updated` - Meta finished reviewing a WhatsApp display-name change. `name.status` carries the outcome (APPROVED, DECLINED, PENDING_REVIEW). Fires only on a review outcome; a name applied without review (`name_status: AVAILABLE_WITHOUT_REVIEW`) produces no event.\n- `whatsapp.account.quality_updated` - A WhatsApp number's quality rating or messaging limit tier changed (Meta `phone_number_quality_update` or `business_capability_update`). Carries the previous and new value of both.\n- `whatsapp.account.status_updated` - Meta restricted, banned, disabled or reinstated the WhatsApp Business Account (Meta `account_update`). Fires once per connected number on the WABA; `status.restrictions` lists what was restricted and until when.\n- `whatsapp.account.alert_received` - Meta sent an account alert (Meta `account_alerts`), for example a messaging-limit increase deferred or an Official Business Account decision.\n- `whatsapp.contact.identity_changed` - A WhatsApp user's identifier changed (new phone number, a regenerated business-scoped user id, or a username adoption). `previous` and `current` carry the phone number, BSUID, parent BSUID and username so you can re-key your records; Zernio already moved the inbox conversation and contact.\n- `call.received` - An inbound call (phone/PSTN or WhatsApp) reached one of your numbers and was routed to its destination\n- `call.ended` - A call ended; carries duration, end reason, cost breakdown, and the recording when enabled\n- `call.failed` - A call failed with a hard error before or during bridging\n- `call.permission_request` - A WhatsApp user accepted or rejected your call-permission request\n- `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\n- `phone_number.stock_available` - An out-of-stock country you watch (POST /v1/phone-numbers/stock-watches) has deliverable numbers again. Fires once per watch, then the watch is consumed. Carries the deliverable count per number type at sweep time (first come, first served).\n- `whatsapp.number.kyc_submitted` - An end customer completed a hosted KYC share link; the number entered regulatory review under your account\n- `whatsapp.number.activated` - A provisioned WhatsApp number finished setup and is ready to connect\n- `whatsapp.number.declined` - A regulated number order was declined in review; nothing activates and nothing is billed\n- `whatsapp.number.action_required` - The regulator asked for more information on a placed number order; the order stays pending until provided\n- `whatsapp.number.verification_required` - A regulated number needs end-user ID verification; carries the link to forward\n- `whatsapp.number.suspended` - An active number was suspended (e.g. failed payment); carries a `reason`\n- `whatsapp.number.reactivated` - A suspended number is usable again\n- `whatsapp.number.released` - A number was released and is no longer usable (terminal); carries a `reason`\n- `verification.approved` - A managed-OTP verification was approved (the user submitted the correct code)\n- `verification.failed` - A managed-OTP verification was exhausted after too many wrong code attempts\n- `commerce.product.created` - A product was created on a connected store\n- `commerce.product.updated` - A product on a connected store changed (fields, status, variants or prices)\n- `commerce.product.deleted` - A product was deleted from a connected store\n- `commerce.order.created` - An order was placed on a connected store\n- `commerce.order.updated` - An order on a connected store changed (payment, fulfilment, cancellation or edits)\n- `commerce.order.refunded` - A refund was issued on an order of a connected store\n- `sms.registration.action_required` - An SMS registration (10DLC or toll-free) is waiting on you: we need answers to some points (before submission, or to fix a carrier rejection), a sole-prop brand needs the code texted to its mobile, or the toll-free carrier asked for more information. Branch on `reason`; `message` says what to do\n- `sms.registration.status_updated` - An SMS registration changed status: changes_requested, requested, pending (with the carriers), approved (ready to send), rejected (we handle the fix) or deactivated\n- `branded_calling.identity.status_updated` - A caller identity changed status: requested (back in our review), changes_requested, rejected, pending_email_verification (filed; the authorizer must enter the code), in_review (carrier vetting), verified, suspended (infringement claim), expired or permanently_rejected\n- `branded_calling.identity.action_required` - A caller identity waits on you: answer a change request, enter the authorizer's code, fix a carrier rejection, respond to an infringement claim or renew an expired verification\n- `branded_calling.number.status_updated` - A number attached to a caller identity changed vetting status (verified = the identity now shows on its calls)\n- `rcs.agent.status_updated` - An RCS agent changed status: changes_requested, brand_vetting, agent_review, testing, launch_review, launching, live, rejected or deactivated\n- `api.changelog.published` - An entry was published to the API changelog (https://docs.zernio.com/changelog). Carries the entry (`type`, `impact`, `platforms`, markdown `message`, docs `url`) and the deterministic OpenAPI diff behind it (`changes`: operations and schemas added, removed and modified). Tenant-free: one broadcast reaches every subscription that opted in. Back-fill with GET /v1/changelog.\n- `contact.tag_added` - A tag was added to a contact. `source` says who wrote it: `api` (the API or dashboard), `workflow` (an add_tag node) or `automation` (a comment-automation link click). One event per tag actually added; re-adding a tag the contact already has fires nothing\n- `contact.tag_removed` - A tag was removed from a contact (same `source` vocabulary)\n- `contact.field_changed` - A contact custom field changed value. Carries `field` (the slug), `previousValue` and `value` (null when the field was absent before or was removed), and `source`\n- `sequence.enrolled` - A contact was enrolled in a sequence (via the API or a workflow enroll_sequence node)\n- `sequence.exited` - A contact left a sequence. `exitReason` is `completed` (the last step was sent), `replied`, `manual` (unenrolled through the API), `failed` (the step kept failing to send) or `unsubscribed`\n- `workflow.run.started` - A workflow run started for a conversation\n- `workflow.run.completed` - A workflow run ended. `execution.status` is `completed`, or `exited` when the run was ended on purpose before its last node (a handoff, or a button that switched the contact to another workflow)\n- `workflow.run.failed` - A workflow run failed; `error` says which node failed and why\n- `support.run.completed` - The Support Assistant finished a question. `run.status` is `completed`, or `needs_human` when the assistant handed the question to a person; `run.answer` holds the answer. The `run` object is exactly what `GET /v1/support/runs/{runId}` answers\n- `support.run.failed` - A Support Assistant question failed or expired. Failed runs are not billed, so `run.costUsd` is 0\n- `campaign_submission.received` - A creator submitted a post to a campaign and its tracking window opened\n- `campaign_submission.flagged` - A submission gained a fraud flag it did not carry before, at submission (for example `duplicate_post` or `duplicate_media`) or on a later sync (`view_spike`, `low_authenticity`, `account_restricted`, `unreachable`, `post_deleted`, `x_read_cap`, `paid_views`, `organic_unverified`); `submission.flags` lists every flag it carries\n- `campaign_submission.pending_review` - A submission is ready for review: a CPM submission reached `minViewsToEarn` or a pool submission `minViewsToQualify`; per-post submissions on the first accrual pass after submission\n- `creator_campaign.budget_exhausted` - A campaign's earnings reached its budget; nothing more accrues until budget is freed. Fires once per campaign\n- `campaign_submission.approved` - An operator approved a submission; what it earned so far moves to owed with the campaign's hold, and later earnings post straight to owed\n- `campaign_submission.rejected` - An operator rejected a submission; its tracking window is cancelled and its unsettled earnings return to the campaign budget\n- `creator_campaign.closed` - A campaign closed, by the operator or once `endsAt` passed and every tracking window had its final read. A pool campaign is split among participants at this moment\n- `campaign_payout.payable` - A participant's held earnings matured and are payable; `payout.payableCents` is the participant's whole payable balance\n- `campaign_payout.settled` - A payout to a participant was recorded; `payout.settlement` holds the amount and the external reference\n- `campaign_payout.failed` - A treasury payout to a participant did not reach the creator: Stripe refused it (`returned`), it could not be confirmed within 24 hours (`stale`), or it was reversed after it was sent (`reversed`). The amount is payable again, minus any amount a rejection made while the payout was in flight claws back to the campaign budget; `payout.failure` holds the transfer and the reason\n- `campaign_participant.joined` - A creator joined a campaign, by opening their invite link or joining from the open link. Fires once per participant\n- `campaign_participant.suspended` - An operator suspended a participant; they can no longer connect accounts or submit posts to the campaign\n- `campaign_participant.removed` - An operator removed a participant from the campaign\n- `webhook.test` - Test event sent when verifying a webhook endpoint\n\nEvery delivery carries `X-Zernio-Event` (the event name) and `X-Zernio-Event-Id` (the payload's `id`, a UUID generated once when the event is emitted). That id is identical on every subscription that receives the event, on every automatic retry and on a redelivery via `POST /v1/webhooks/logs/redeliver`, so it is the key to dedupe on. Payloads are signed with HMAC-SHA256 via the `X-Zernio-Signature` header when the subscription has a secret. Legacy `X-Late-*` copies of these three headers are still sent and will be removed in a future major version.\n\n### Finding the connected account id\n\nThe top-level `id` is the event id (the dedupe key, also sent as `X-Zernio-Event-Id`). It is never an account, post or other resource id. The connected account lives here:\n\n| Event family | Account id |\n| --- | --- |\n| `account.*`, `analytics.synced` | `account.accountId` |\n| `post.tracking_completed`, `post.authenticity_changed` | `post.accountId` |\n| `message.*`, `reaction.received`, `referral.received`, `conversation.*`, `comment.received`, `review.*`, `lead.received`, `call.*` | `account.accountId` (`account.id` carries the same value, kept for compatibility; `call.received`, `call.ended` and `call.failed` also carry `call.accountId`) |\n| `post.platform.*`, `post.tiktok.url_resolved` | `account.accountId` (the target this event is about; `post.platforms[].accountId` lists every target) |\n| `post.scheduled`, `post.published`, `post.failed`, `post.partial`, `post.cancelled`, `post.recycled` | `post.platforms[].accountId`, one per target; there is no top-level account |\n| `post.external.*` | `account.accountId` (also `post.accountId`) |\n| `ad.status_changed`, `ad.review.*`, `ad.video.processed`, `ad_rule.triggered`, `whatsapp.template.*`, `whatsapp.account.*`, `whatsapp.contact.identity_changed` | `account.accountId` |\n| `whatsapp.automatic_event`, `automation.*` | top-level `accountId` |\n| `whatsapp.number.*`, `sms.registration.*` | none; `number.id` / `registration.id` are the number and registration ids, `number.profileId` / `registration.profileId` the profile |\n| `campaign_submission.*` | none; `submission.platformPostId` is the post and `campaign.id`, `participant.id`, `creator.id` identify the rest |\n| `creator_campaign.*` | none; `campaign.id` is the campaign |\n| `campaign_payout.*` | none; `campaign.id`, `participant.id` and `creator.id` identify the payout |\n| `campaign_participant.*` | none; `campaign.id`, `participant.id` and `creator.id` identify the participant |\n| `verification.*`, `phone_number.stock_available`, `api.changelog.published`, `webhook.test`, `contact.*`, `sequence.*`, `workflow.run.*` | none (`sequence.*` and `workflow.run.*` still reach subscriptions scoped to the sending account) |\n\n## Full Documentation\n\nFor complete guides, platform-specific details, and SDK references, visit [docs.zernio.com](https://docs.zernio.com).\n\n## SDKs\n\nOfficial 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.\n"},"servers":[{"url":"https://zernio.com/api","description":"Production"},{"url":"http://localhost:3000/api","description":"Local"}],"tags":[{"name":"Ledger","description":"Read-only access to double-entry ledger balances and entries for your team. Every operation belongs to the `money` resource group."},{"name":"Creator Campaigns","description":"Pay creators for verified performance. A campaign sets the economics (CPM, per post or pool), a budget and the platforms. Creators join through an invite link, connect their accounts read-only and submit their posts.\n\nZernio tracks each post through a tracking window, scores its authenticity, accrues earnings in a ledger and flags anything suspicious, never rejecting on its own. You review submissions, approve or reject them, and settle what is payable from your own rails (or, later, from your Zernio balance).\n\nAmounts are USD cents. Earnings move through four states per participant: accruing (earned, not approved), owed (approved, on hold for `holdDays`), payable and settled.\n\nWebhooks: `campaign_submission.*`, `creator_campaign.*`, `campaign_payout.*` and `campaign_participant.*`.\n\nCreator campaigns run on usage-based billing; every operation answers 403 `feature_not_available` for a workspace not on it. Every operation belongs to the `creator_campaigns` resource group.\n"},{"name":"Treasury","description":"Fund a balance by card, then transfer money to payees (creators, ad accounts) through Zernio. The dashboard calls this your Balance. Requires usage-based billing. Every operation belongs to the `money` resource group.\n\n- Money writes (top-ups, transfers, treasury settles, payout batches) need an owner, admin or billing admin, signed in or through a full-access key they created.\n- Reading the team's balance, top-ups, transfers and payees needs a full-access key or a signed-in session; a profile-scoped key answers 403.\n"},{"name":"Creator Portal","description":"The pages a creator uses behind a campaign link: read the campaign, join, connect accounts, submit posts and set up payouts.\n\n**Auth:** no API key. The `token` in the path (an open invite token or a participant token) is the only credential, so treat a participant token like a password.\n\n- An invalid, unknown or expired token always answers the same 404.\n- Write operations are rate limited per token and IP address (429).\n\nBuild your own creator experience on these, or send creators to the Zernio-hosted page at `https://zernio.com/join/{token}`.\n"},{"name":"Posts","description":"Create, schedule, list, update, and delete posts across all connected accounts.\n"},{"name":"Blogs","description":"Manage blogs and blog articles on connected accounts. Currently supported\nfor Shopify accounts (scopes read_content and write_content). Blogs are\nthe containers; articles are the posts inside them. All content lives on\nthe platform; Zernio proxies it and stores nothing.\n"},{"name":"Products","description":"Deprecated: use the Commerce endpoints (`/v1/commerce/products`), which\nreturn the same catalog in the platform-neutral shape with prices that\ncarry their currency. These endpoints keep working with their original\nresponse for existing integrations.\n"},{"name":"Commerce","description":"One API over every connected store: write against it once and it works for each supported platform.\n\n**Platforms:** Shopify, and WooCommerce on self-hosted WordPress sites (a connected WordPress account is the store; commerce objects report `platform: woocommerce`). TikTok Shop and more follow. Each operation lists its platforms in `x-platforms`.\n\nPick the store with `accountId` (a query parameter on reads, a body field on writes).\n\n**Conventions shared by every Commerce endpoint:**\n\n- Money is `{ amount, currency }` (CommerceMoney): amount as a decimal string, currency never null. Write bodies take a bare decimal amount in the store's currency.\n- Timestamps are ISO 8601 UTC.\n- `status` uses the Zernio vocabulary; the platform's raw value is always returned as `platformStatus`.\n- Lists return `{ <resource>, nextCursor }` with an opaque cursor.\n- An operation a platform cannot serve answers 400 with code `platform_not_supported`. `GET /v1/commerce/store` lists a store's `capabilities` up front.\n\nAll data lives on the platform; Zernio proxies it and stores nothing.\n"},{"name":"Users","description":"Read the authenticated user and team members.\n"},{"name":"Usage","description":"Usage and metering.\n\n`GET /v1/usage` is dual-mode:\n\n- Bare calls return the plan / quota snapshot (back-compat, same as `/v1/usage-stats`).\n- Calls with `range` / `granularity` params return usage METERING: billed spend (USD) by product family (accounts, numbers, imessage, calls, sms, messages, verify, dlc, xApi, ads, credits, other) over any window, from the usage-based invoice breakdown (also served at `GET /v1/usage/daily`).\n\nThe `/v1/usage/<domain>` spokes (calls, sms) meter per-domain consumption volumes over a window. `GET /v1/billing` is the billing statement (balance, credits, caps, payment status).\n"},{"name":"Profiles","description":"Manage profiles (named groups of accounts).\n"},{"name":"Accounts","description":"Manage connected accounts: list, fetch, update, disconnect, and read account health.\n"},{"name":"Account Groups","description":"Manage account groups (collections of accounts used for cross-posting and organization).\n"},{"name":"API Keys","description":"Create, list, and revoke API keys used to authenticate requests.\n\n**Resource groups.** A key can opt out of any of the fifteen groups via `disabledResourceGroups` at creation: publishing, engagement, messages, contacts, analytics, ads, telephony, accounts, billing, webhooks, commerce, calendar, files, creator_campaigns, money. Omit the field for a legacy full-access key.\n\nA key with any group disabled:\n\n- mints with the `zrk_` prefix\n- is refused on operations in those groups with 403 `insufficient_permissions` plus `required_group`\n- can never manage API keys, invites, connected apps, or member identity\n\nEach operation publishes its group as `x-resource-group`. There is no update endpoint: duplicate the key with different groups and revoke the old one.\n"},{"name":"Connected Apps","description":"List and revoke the OAuth clients (AI assistants and MCP connectors) authorized\non the account.\n\nConnector 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.\n"},{"name":"Invites","description":"Generate invite tokens for adding members to a team.\n"},{"name":"Connect","description":"OAuth and credential flows for connecting accounts, plus per-platform selection\nsteps (Facebook pages, Pinterest boards, LinkedIn organizations, Google Business Profile locations, etc.).\n"},{"name":"Email","description":"Read, send and organize mail in connected Google Workspace and Microsoft 365 mailboxes. Connect with `scopes=email`."},{"name":"Calendar","description":"Calendars, events, RSVPs, free/busy and cross-account availability for connected Google and Microsoft accounts. Connect with `scopes=calendar`."},{"name":"Files","description":"Google Drive and OneDrive files of a connected account: list, download, upload, folders, rename, move, trash and share links. Connect with `scopes=files`. Attach a file to a post as `{ fileId, accountId }` in `mediaItems`.\n\n**Google Drive access is per file.** Google accounts are connected with Google's `drive.file` scope, not full Drive access. Zernio, and so your integration, can open only:\n\n- files created through Zernio (`POST /v1/files`, `POST /v1/files/folders`), and\n- files the user picked in Google Picker: in the Zernio dashboard, or on a hosted picker page you open with `POST /v1/files/picker-sessions`.\n\nEverything else in the user's Drive is invisible. Listing returns only the files above, and a folder the user never picked lists empty (picking a folder does not grant its contents).\n\nAny per-file call on another id answers 404 `resource_not_found` with `details.reason: file_not_granted`. The fix is always to have the user pick the file. Picked files in shared drives work. Grants last until the user removes Zernio from their Google account.\n\nOneDrive (Microsoft accounts) has no such limit: the account reaches every file the user can see, and picker sessions do not apply.\n"},{"name":"Media","description":"Upload and presign media (images, videos, documents) for use in posts.\n"},{"name":"Reddit Search","description":"Search Reddit posts and browse subreddit feeds.\n\nOrganic Reddit is temporarily unavailable: Reddit has blocked third-party apps from its API, so Reddit posting, messages, analytics and the Reddit endpoints return 503 `PLATFORM_DISABLED` until Reddit restores access. Your Reddit accounts stay connected. Reddit Ads is not affected.\n"},{"name":"GMB Reviews","description":"Google Business Profile reviews: list reviews and reply to them.\n"},{"name":"GMB Food Menus","description":"Read and update Google Business Profile food menus.\n"},{"name":"GMB Location Details","description":"Read and update Google Business Profile location details.\n"},{"name":"GMB Media","description":"Manage Google Business Profile media (photos and videos): list, upload, and delete.\n"},{"name":"GMB Attributes","description":"Read and update Google Business Profile attributes.\n"},{"name":"GMB Place Actions","description":"Manage Google Business Profile place action links (booking, ordering, reservations, etc.).\n"},{"name":"GMB Services","description":"Read and replace the services a Google Business Profile location offers.\n"},{"name":"GMB Verifications","description":"Verify a Google Business Profile location: read its verification state, fetch the available\nmethods, start a verification and complete it with the code Google sends.\n"},{"name":"Discord","description":"Discord-specific endpoints for managing webhook identity (display name and avatar), switching channels, and listing guild channels.\n"},{"name":"Slack","description":"Slack-specific endpoints for a connected Slack workspace, such as listing its members.\n"},{"name":"LinkedIn Mentions","description":"Resolve LinkedIn organization and person mentions for use in posts.\n"},{"name":"Instagram","description":"Instagram-specific read endpoints: list a connected account's Stories and fetch\nper-Story insights. All endpoints require an accountId parameter identifying the\nInstagram-connected account.\n"},{"name":"Queue","description":"Manage posting-queue time slots and preview the upcoming queue.\n"},{"name":"Analytics","description":"Post and account analytics across platforms (insights, demographics, follower history,\nbest time to post, content decay, and aggregated metrics).\n"},{"name":"Inbox Analytics","description":"Inbox messaging analytics: message volume, a day by hour heatmap, source breakdown, response\ntimes, top accounts and per-conversation stats. Requires Inbox addon.\n"},{"name":"Inbox Access","description":"Check and manage inbox feature access.\n"},{"name":"Messages","description":"Unified inbox API for managing conversations and direct messages across all connected accounts.\nAll endpoints aggregate data from multiple accounts in a single API call.\nRequires Inbox addon.\n"},{"name":"Comments","description":"Unified inbox API for managing comments on posts across all connected accounts.\nSupports commenting on third-party posts for platforms that allow it (YouTube, X, Reddit, Bluesky, Threads).\nAll endpoints aggregate data from multiple accounts in a single API call.\nRequires Inbox addon.\n"},{"name":"Reviews","description":"Unified inbox API for managing reviews on Facebook Pages and Google Business Profile accounts.\nAll endpoints aggregate data from multiple accounts in a single API call.\nRequires Inbox addon.\n"},{"name":"Mentions","description":"Unified inbox API for managing mentions across connected accounts.\nCurrently supports LinkedIn organization mentions.\nRequires Inbox addon.\n"},{"name":"Twitter Engagement","description":"X-specific engagement endpoints for retweeting, bookmarking, and following.\nRate limits: 50 requests per 15-min window per user. Retweets share the 300/3hr creation limit with tweet creation.\n"},{"name":"Validate","description":"Pre-flight validation endpoints. Check post content, character limits, media URLs, and subreddit existence before publishing.\n"},{"name":"Account Settings","description":"Platform-specific account settings: Facebook persistent menu, Instagram ice breakers, and Telegram bot commands.\n"},{"name":"Contacts","description":"Cross-platform contact management (CRM). Contacts are unified identities linked to platform-specific\nchannels (phone, IGSID, etc.). Created automatically when messages arrive, or manually via API.\n"},{"name":"Custom Fields","description":"Custom field definitions for contacts. Define fields (text, number, date, boolean, select) that can be\nset on any contact for segmentation and personalization.\n"},{"name":"Broadcasts","description":"Platform-agnostic broadcast campaigns. Send bulk messages to contacts via any inbox platform.\nWhatsApp broadcasts use templates; other platforms use generic messages.\n"},{"name":"Sequences","description":"Drip campaign sequences. Send a series of messages to enrolled contacts with configurable delays\nbetween steps. Supports auto-exit on reply or unsubscribe.\n"},{"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).\n\nUnlike Sequences (linear, time-based drips), Workflows are event-driven and interactive.\n\nFully supported on WhatsApp, Instagram, and Messenger. `send_message` template and interactive modes are WhatsApp-only; cards, buttons, quick replies and message tags are Instagram and Messenger only.\n"},{"name":"Comment Automations","description":"Comment-to-DM growth automations. Set up keyword triggers on Instagram/Facebook so\ncommenters automatically receive a DM. Scope per post or account-wide (omit\n`platformPostId` to match comments on every post on the account, with unlimited\nautomations stacked per account). Supports dedup, optional public comment reply, and\nauto-creates contacts.\n"},{"name":"Ad Rules","description":"Rules that check campaigns or ad sets on a schedule and pause, reactivate, rebudget or notify\nwhen their metrics cross a threshold. Requires the Ads add-on.\n"},{"name":"Automations","description":"One API for every automation: ad rules that check ads on a schedule, event automations that run when something happens in Zernio, and scheduled automations that check posts. Each has a `trigger`, the `subjects` it checks, the `steps` it takes and its `limits`.\n\nAn ad rule is also readable under `/v1/ads/rules` with the same id. Creating, editing, activating and previewing an ad rule needs ads access; nothing else does.\n"},{"name":"Ad Campaign Results","description":"Your own results per campaign and day (qualified leads, sales, revenue), uploaded by API or file, so rules and reports use them next to spend. Requires the Ads add-on.\n"},{"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.\n\nPer-operation platform support is shown by the platform badges. Requires the Ads add-on.\n\n**Status model.** Every level keeps its own on/off switch, as in each platform's own UI: Meta `configured_status`, TikTok `operation_status`, Google `status`, LinkedIn `status`, Pinterest `status`, X `entity_status`, ChatGPT (OpenAI) `status`, Reddit `configured_status`.\n\n- **Own switch** is what you set. Ads return it as `configuredStatus`, ad sets as `platformAdSetStatus`, campaigns as `platformCampaignStatus`. Meta and Reddit ad sets return their `effective_status` in `platformAdSetStatus` instead (e.g. `CAMPAIGN_PAUSED`).\n- **Delivery status** (`status`, and the raw `platformStatus` on ads) is derived: an object delivers only when its own switch AND every switch above it are on. An ad switched on under a paused campaign reads `configuredStatus: ACTIVE` with `status: paused`.\n- **No cascade.** Pausing or resuming a campaign or ad set writes that object's switch only. Children keep their own switches, so a resume never re-enables an ad or ad set you paused individually. Resume each paused level you want live.\n- No cascade is native platform behavior (Google: \"Resuming a campaign only enables the campaign level\"; Meta reports the inherited pause as CAMPAIGN_PAUSED / ADSET_PAUSED on the child).\n- **Created paused = top-most object paused.** A create with `status: PAUSED` pauses only the highest object that request creates, with everything below switched on. One resume of that object brings the whole new tree live.\n- Examples: a new campaign is paused with its ad set and ad on; a new ad set in an existing campaign is paused with its ad on; an ad attached to an existing ad set is itself paused.\n- X has no per-ad switch (a promoted post follows its line item).\n"},{"name":"Ad Creatives","description":"Creative assets: the standalone creative library (create/reuse/rename), the ad-account image library\n(list + base64 upload), rendered ad previews, and product catalogs for Advantage+/dynamic ads. Meta only.\nRequires the Ads add-on.\n"},{"name":"Ad Audiences","description":"Custom audiences for targeting: customer lists (hashed upload), website + engagement + lookalike\naudiences, and reusable saved-targeting presets. Creation support varies by platform (badges show which);\nLinkedIn adds company-list and engagement segments.\nRequires the Ads add-on.\n"},{"name":"Ad Targeting","description":"Targeting discovery: search interests/behaviors/geo/demographics, estimate reach, and (LinkedIn)\nbid pricing and supply forecasts. Feeds the targeting fields on create.\nRequires the Ads add-on.\n"},{"name":"Ad Library","description":"Competitor and market research over the public ad archives (Meta Ad Library, LinkedIn Ad Library),\nsearched with the customer's own connected token. Requires the Ads add-on.\n"},{"name":"Ad Insights","description":"Measurement: cached aggregate analytics per ad/campaign, plus live Meta Graph insight queries\n(arbitrary fields, breakdowns, filtering, attribution windows) and async report runs.\nRequires the Ads add-on.\n"},{"name":"Conversions","description":"Server-side Conversions API: send + adjust conversion events (with hashed matching and consent/LDU\nforwarding), read Event Match Quality, and manage conversion destinations (pixels/datasets) and their\nad-account associations. Supported on Meta, Google, TikTok, LinkedIn, Pinterest, OpenAI Ads and Reddit\n(badges show per operation).\nRequires the Ads add-on.\n"},{"name":"Messaging Ads","description":"Click-to-message and click-to-call destination ads: WhatsApp (CTWA), Messenger, Instagram Direct,\nand Call ads. Meta only.\nRequires the Ads add-on.\n"},{"name":"Reach and Frequency","description":"Fixed-price reserved (Reach & Frequency) buying: quote a prediction, reserve price + inventory, and\nbuy via a RESERVED campaign. Meta only.\nRequires the Ads add-on.\n"},{"name":"Lead Gen","description":"Instant lead forms on Facebook Pages: create/list/archive forms and retrieve (or test) their leads.\nMeta only.\nRequires the Ads add-on.\n"},{"name":"Ad Accounts","description":"Ad accounts and operational/diagnostic reads: list accounts, account finances, change/audit log,\nA/B studies, high-demand periods, ad labels, DSA defaults + recommendations, and Business Managers\n(Meta) / Business Centers (TikTok).\nRequires the Ads add-on.\n"},{"name":"Tracking Tags","description":"Manage the platform measurement tag: the thing you create, install on a website, send events to, and target ads against. Currently Meta-only, where it is a Pixel. Requires the Ads add-on.\n\nThe surface is platform-neutral, so other platforms (Pinterest Tag, LinkedIn Insight Tag, etc.) can be added without changing the contract.\n\nYou can:\n\n- create a tag;\n- get it, including the install code snippet;\n- rename it and adjust matching/cookie/data-use settings;\n- share it with ad accounts;\n- read aggregated event stats.\n"},{"name":"Product Catalogs","description":"Manage the Meta Commerce catalogs behind catalog (dynamic product) ads: catalogs, products, batch\nproduct writes, feeds and feed uploads, and product sets.\nRequires the Ads add-on.\n"},{"name":"Business Agent","description":"Provision and operate Meta Business Agent, Meta's own AI agent, on a connected WhatsApp number without the merchant opening Business Manager. You can:\n\n- check eligibility and setup state\n- create the agent and turn it on or off\n- feed it knowledge (business information, FAQs, websites, files)\n- give it skills and UI skills\n- wire connectors and tools to your own APIs\n- cap usage with budgets\n- test it in Meta's sandbox, send it business events, and run evaluations\n\n**Two manual steps.** By Meta's design these have no API; `GET .../business-agent` reports both.\n\n- The merchant accepts the Meta Business Agent terms in WhatsApp Manager. Until then every call answers `business_agent_terms_not_accepted`.\n- A payment method is attached to the Business Agent billable account in Billing Hub. Without it the agent is on but Meta delivers no messages (allowlisted-only testing is exempt).\n\nWhile the agent answers a conversation, your inbox receives it on the standby path, and a reply from Zernio takes control back.\n\n**Requirements.** Every call needs the WhatsApp social account id, the Inbox add-on, and a number managed through the Cloud API. A coexistence number that still runs the in-app Business AI is not eligible.\n"},{"name":"Webhooks","description":"Configure webhooks for real-time notifications, from the dashboard (Settings → Webhooks) or via this API.\n\n**Events:**\n\n- Posts: `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`, `post.tracking_completed`, `post.authenticity_changed`\n- Accounts and analytics: `account.connected`, `account.disconnected`, `account.permissions_changed`, `account.ads.initial_sync_completed`, `account.ads.sync_failed`, `account.ads.sync_recovered`, `account.rate_limited`, `analytics.synced`\n- Messages: `message.received`, `message.sent`, `message.edited`, `message.deleted`, `message.delivered`, `message.read`, `message.played`, `message.failed`, `reaction.received`, `referral.received`, `conversation.started`, `conversation.control_changed`\n- Calls: `call.received`, `call.ended`, `call.failed`, `call.permission_request`\n- Engagement and leads: `comment.received`, `review.new`, `review.updated`, `review.deleted`, `review.restored`, `lead.received`\n- Ads: `ad.status_changed`, `ad.created`, `ad.updated`, `campaign.created`, `campaign.updated`, `ad.review.approved`, `ad.review.rejected`, `ad.delivery_issue`, `campaign.budget.depleted`, `ad_account.status_changed`, `ad.video.processed`, `ad_rule.triggered`\n- WhatsApp: `whatsapp.template.status_updated`, `whatsapp.template.category_updated`, `whatsapp.account.name_status_updated`, `whatsapp.account.quality_updated`, `whatsapp.account.status_updated`, `whatsapp.account.alert_received`, `whatsapp.contact.identity_changed`, `whatsapp.automatic_event`\n- WhatsApp numbers: `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`\n- Telephony: `phone_number.stock_available`, `verification.approved`, `verification.failed`, `sms.registration.action_required`, `sms.registration.status_updated`, `branded_calling.identity.status_updated`, `branded_calling.identity.action_required`, `branded_calling.number.status_updated`, `rcs.agent.status_updated`\n- Commerce: `commerce.product.created`, `commerce.product.updated`, `commerce.product.deleted`, `commerce.order.created`, `commerce.order.updated`, `commerce.order.refunded`\n- Contacts and automations: `contact.tag_added`, `contact.tag_removed`, `contact.field_changed`, `contact.updated`, `contact.deleted`, `sequence.enrolled`, `sequence.exited`, `workflow.run.started`, `workflow.run.completed`, `workflow.run.failed`, `support.run.completed`, `support.run.failed`, `automation.check.completed`, `automation.action.applied`, `automation.action.failed`, `automation.action.unknown`, `automation.alert.opened`, `automation.alert.escalated`, `automation.alert.resolved`\n- Creator campaigns: `campaign_submission.received`, `campaign_submission.flagged`, `campaign_submission.pending_review`, `campaign_submission.approved`, `campaign_submission.rejected`, `creator_campaign.budget_exhausted`, `creator_campaign.closed`, `campaign_payout.payable`, `campaign_payout.settled`, `campaign_payout.failed`, `campaign_participant.joined`, `campaign_participant.suspended`, `campaign_participant.removed`\n- Calendar and files: `calendar.event.created`, `calendar.event.updated`, `calendar.event.deleted`, `file.created`, `file.updated`, `file.deleted`, `file.picked`\n- Other: `api.changelog.published`, `webhook.test`\n\n**Headers.** Every delivery carries `X-Zernio-Event` (event name) and `X-Zernio-Event-Id` (the payload `id`). That UUID is minted once per event and is identical across every subscribed endpoint, automatic retry and redelivery, so dedupe on it.\n\n**Security.** Optional HMAC-SHA256 signature in the `X-Zernio-Signature` header: configure a secret key to enable verification. Custom headers are supported. Legacy `X-Late-Event`, `X-Late-Event-Id` and `X-Late-Signature` duplicates are still sent and will be removed in a future major version.\n\n**Resource groups.** Every event belongs to one group:\n\n- publishing: `post.*`\n- messages: `message.*`, `reaction.*`, `conversation.*`, `call.*`, `whatsapp.automatic_event`, `sequence.*`, `workflow.run.*`\n- engagement: `comment.*`, `review.*`\n- contacts: `lead.*`, `contact.*`\n- ads: `ad.*`, `ad_account.*`, `ad_rule.*`, `campaign.*`\n- accounts: `account.*`, `whatsapp.template.*`, `whatsapp.account.*`\n- analytics: `analytics.*`\n- telephony: `whatsapp.number.*`, `verification.*`, `sms.registration.*`\n- creator_campaigns: `campaign_submission.*`, `creator_campaign.*`, `campaign_payout.*`, `campaign_participant.*`\n- webhooks: `api.changelog.published`, `webhook.test`\n\nSupport Assistant events (`support.run.*`) belong to no single group: they need every resource group enabled and a first-party full-scope caller (a session or a full-scope key, never an OAuth token or a profile-scoped key).\n\nTwo independent controls use that mapping:\n\n1. 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.\n2. Each subscription carries its own `disabledResourceGroups` denylist. Events in a disabled group are dropped before delivery to that endpoint, on live delivery and every replay path, whichever key or session created the subscription.\n\nChanging the denylist applies to every event emitted after the change.\n\nEvents already queued can still be delivered for up to five minutes after enqueue, because the delivery worker trusts a five-minute enqueue-time snapshot before re-checking. Absent or empty means the subscription receives everything it subscribes to (the behavior of every subscription created before the field existed).\n\n**Profile and account filters.** A subscription can carry `profileIds` (an allowlist of profiles) and `accountIds` (an allowlist of connected accounts, same semantics). Each non-empty list narrows delivery; a subscription with both must satisfy both. Absent or empty means every profile (or every account).\n\nA scoped subscription only gets events it can attribute to one of those profiles: the profile of the connected account behind the event, or, for an aggregate `post.*` event, the profile of every account the post targets (a post spanning two scoped endpoints' profiles reaches both).\n\nThis lets an integrator route the profile holding test accounts to a staging endpoint while a second subscription, scoped to production profiles, keeps production traffic.\n\nEvents that belong to no profile (`verification.*`, `phone_number.*`, and a legacy post whose accounts were deleted) reach only unscoped subscriptions. The filter runs when an event is emitted; redelivery replays a delivery already made to that endpoint, and test fires ignore it.\n"},{"name":"Support Assistant","description":"Get help from the Zernio Support Assistant without leaving your code. Ask about a post, a connected account or a profile in your workspace, and the assistant looks into it and answers.\n\n**How it works:** each question starts a run that answers asynchronously.\n\n- Ask with `POST /v1/support/runs`.\n- Receive the answer through the `support.run.completed` and `support.run.failed` webhooks, or poll `GET /v1/support/runs/{runId}`.\n- List a thread's answers with `GET /v1/support/runs?threadId=`.\n\n**Pricing:** you pay per question. Most cost between $0.10 and $0.50, none more than its `maxCostUsd` cap ($3 by default), and failed questions are free.\n\nRequires an unrestricted API key and a usage-based plan with a card on file.\n"},{"name":"Webhook Events","description":"Incoming webhook deliveries sent by Zernio to your configured endpoint URL.\n"},{"name":"Changelog","description":"The API changelog (https://docs.zernio.com/changelog) as data: the entries the `api.changelog.published` webhook announces, newest first, for agents that automate against API changes and need to back-fill what they missed.\n"},{"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.\n"},{"name":"WhatsApp","description":"WhatsApp Business API. Template, business profile, and phone number endpoints.\nAll endpoints require an accountId parameter identifying the WhatsApp-connected account.\n"},{"name":"WhatsApp Calling","description":"Voice calling over the WhatsApp Business API: enable/disable calling on a number,\nconfigure call hours and permissions, and place or list calls.\nAll endpoints require an accountId parameter identifying the WhatsApp-connected account.\n"},{"name":"WhatsApp Templates","description":"Browse Meta's pre-approved WhatsApp template library. Use these read-only lookups to\ndiscover library templates you can import as your own message templates.\nAll endpoints require an accountId parameter identifying the WhatsApp-connected account.\n"},{"name":"WhatsApp Flows","description":"WhatsApp Flows let you build native interactive forms, surveys, and booking experiences inside WhatsApp.\n\nFlows 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).\n\nAll endpoints require an accountId parameter identifying the WhatsApp-connected account.\n"},{"name":"Phone Numbers","description":"Buy and manage phone numbers. A phone number is a platform-independent unit;\nWhatsApp, SMS, and Voice are features you enable on it. Purchase, search\ninventory, complete country KYC, and release numbers here; turn features on\nvia the per-number sub-resources (`/v1/phone-numbers/{id}/voice`, `/sms`,\n`/whatsapp/...`). Requires a paid plan.\n"},{"name":"Verify","description":"Managed one-time passcodes (OTP) for phone verification. Two calls\nhandle the whole lifecycle: create a verification (we generate the\ncode, deliver it by SMS from a phone number on your account, and store\nonly its hash) and check the code the user typed. Usage-based billing\nonly.\n"},{"name":"WhatsApp Phone Numbers","description":"Deprecated namespace: phone numbers moved to `/v1/phone-numbers` (a number is\nplatform-independent; WhatsApp is one feature on it). These aliases keep\nworking with the same contracts, but new integrations should use the\nPhone Numbers endpoints.\n"},{"name":"WhatsApp Sandbox","description":"Shared WhatsApp sandbox: a Zernio-owned WhatsApp number every user can test against\nwithout provisioning their own. Send the verified sandbox template to phones you\nactivate via a reply-based verification flow. Designed for testing message flows,\nbot replies, and webhook payloads end-to-end with zero number-purchase overhead.\n"},{"name":"Calls","description":"Unified call history across every number you own: WhatsApp Business Calling and\nregular phone (PSTN) calls in one list, newest first, without fanning out one\nrequest per number. Each row carries `channel` and `accountId` so you can fetch\ndetails and recordings from the matching channel-specific endpoint.\n"},{"name":"Voice","description":"Regular phone (PSTN) calling on your numbers.\n\n- Enable voice on a number and route inbound calls to your own AI voice agent (Vapi/Retell), a phone, or a SIP endpoint.\n- Voicemail, business-hours routing, IVR, recording, and transcription.\n- Place outbound calls, manage live ones (end, blind-transfer), resolve recordings, and drive the browser softphone.\n"},{"name":"Branded Calling","description":"Show your business name, logo and reason for calling on the callee's phone instead of a bare number.\n\nSteps: register the business, create a caller identity (name, logo, call reasons, references), pass review, then attach US numbers with a signed Letter of Authorization.\n\nDisplays on calls to US mobiles on T-Mobile and Verizon. Eligibility is verified; display is never guaranteed by the carriers.\n"},{"name":"SMS","description":"SMS/MMS on your numbers: enable SMS on a number, send messages, validate recipient\nnumbers, export STOP opt-outs, and complete the US carrier registration (10DLC or\ntoll-free) required before US traffic delivers.\nEnabling SMS on a number, carrier registration and sender IDs require usage-based billing.\n"},{"name":"RCS","description":"Branded, verified RCS messaging. Each agent is a sender with your name, logo, banner and verified tick, owned by a vetted company (brand). The US is self-serve end to end; in other markets our team files with the carriers after review.\n\n**Lifecycle:** `requested` (our review, nothing filed or billed) -> `brand_vetting` -> `agent_review` -> `testing` (invite test phones, then send the launch filing) -> `launch_review` (our review) -> `launching` (carrier review) -> `live`.\n\nSide exits: `changes_requested`, `rejected`, `deactivated`. Status changes fire `rcs.agent.status_updated`.\n\n**Pricing per agent:**\n\n- US: $150 when we submit it to the carriers, $750 when it goes live, then $160/mo month to month from go-live (nothing monthly during carrier review).\n- Other markets: $150 when filed, then $75/mo from go-live.\n- Messages (sent and received): 1.5x carrier cost.\n\nSet `smsFallbackFrom` to one of your SMS-enabled numbers and phones without RCS get the message as SMS.\n"},{"name":"iMessage","description":"Two-way iMessage on provider-provisioned senders. Order or register a sender\non a profile, then send and receive through the inbox conversation endpoints\n('platform: imessage').\n"},{"name":"Feedback","description":"Report a bug, a missing feature or a docs gap straight from your integration.\nBuilt for AI agents: when an agent hits something the API cannot do, it can\nsay so here in a structured way instead of failing silently.\n"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API key authentication: send your Zernio API key in the Authorization header, prefixed with Bearer."},"connectToken":{"type":"apiKey","in":"header","name":"X-Connect-Token","description":"Short-lived connect token for API users during OAuth flows. \nAutomatically generated when initiating OAuth without a browser session.\nValid for 15 minutes. Connect tokens are scoped to the intended profile\nand platform and are accepted only by connection-flow endpoints that\nexplicitly list this security scheme.\n"}},"parameters":{"CreatorPortalToken":{"name":"token","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$"},"description":"A participant token or an open invite token. A malformed token answers 404 like an unknown one."},"EmailAccountId":{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The connected Google or Microsoft account."},"LiveStatusRead":{"name":"live","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Read the on/off switches live from the platform instead of returning synced values. See \"Status freshness\" in the operation description.\n\n- The fresh values are stored (later reads return them too), and the response carries `statusReadAt`, the time of the read.\n- At most 20 platform objects are read per request.\n- Where a read fails (credentials, platform error, no reader on that platform), stored values come back with `statusReadAt: null`.\n\n**On GET /v1/ads/{adId} for a TikTok ad** the creative is read live too: ad text, call to action, landing page, video, format and identity, returned over the stored creative and never stored. See \"Status freshness\" in GET /v1/ads/{adId}.\n\n**On X** the budget is read live too:\n\n- GET /v1/ads/{adId}: `budget`, `adSetBudget`, `campaignBudget` and `budgetLevel` are the line item and campaign budgets X holds now (stored like the switches).\n- Ad set and campaign listings: `budget` is what that line item or campaign holds now (returned, not stored). A row whose budget the other level holds keeps its synced `budget`.\n"},"UnsyncedMetaAdAccountId":{"name":"accountId","in":"query","required":false,"schema":{"type":"string"},"description":"Meta only. A Zernio connection id (Meta Ads or Facebook connection) used when `{adId}` is a Meta ad not in Zernio's synced store, e.g. an Ads Manager ad on an ad account reached only through a Facebook connection.\n\nThe ad is then read live from Meta through that connection, and the response carries `synced: false`. Ads Meta reports as DELETED are returned too, with their status.\n\nSame rules as GET /v1/ads/campaigns/{campaignId}:\n\n- Connection on a profile the API key cannot access: 404.\n- Ad on an ad account outside the connection's selected ad accounts: 403 `ad_account_not_selected`.\n- Id Meta cannot read through the connection, or not an ad (e.g. a campaign or ad set id): 404 `ad_not_found`.\n- Connection that is not Meta: 501.\n\nIgnored when the ad is in the store (its own connection is used). Without it, an unsynced ad answers 404 `ad_not_found`. Writes (PUT, DELETE, status) still need the ad in the store.\n"},"CatalogId":{"name":"catalogId","in":"path","required":true,"schema":{"type":"string"},"description":"Meta product catalog ID (from GET /v1/ads/catalogs)"},"CatalogProductId":{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"Meta product item ID (from the products list; not the retailer id)"},"CatalogAccountId":{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"A facebook, instagram, metaads or whatsapp account ID"},"CatalogTokenAccountId":{"name":"catalogAccountId","in":"query","required":false,"schema":{"type":"string"},"description":"A facebook, instagram or metaads account whose Meta login carries catalog_management; its token performs the call instead of the account's own"},"BusinessAgentAccountId":{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp social account id (the number must be managed through the Cloud API)."},"BusinessAgentConnectorId":{"name":"connectorId","in":"path","required":true,"schema":{"type":"string"}},"BusinessAgentToolId":{"name":"toolId","in":"path","required":true,"schema":{"type":"string"}},"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.\n\n- Same key + same body: replays the original response.\n- Same key + different body: 422.\n- Key still processing: 409.\n\nA request cut off mid-handler (e.g. by a function timeout) can leave its key in progress, answering 409 until the key expires after 24 hours.\n\nOn the Ads create, boost and duplicate endpoints, a same-body retry runs again once the cut-off request started more than 15 minutes ago.\n"},"AutomationBacktestDays":{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":90,"default":30},"description":"How many whole days before today to replay. Today is not replayed."}},"headers":{"BackfillRetryAfter":{"description":"Recommended delay before retrying, in seconds.","schema":{"type":"integer","example":60}}},"responses":{"CreatorPortalLinkNotFound":{"x-summary":"The link token is malformed, unknown or expired: ask the creator for a fresh link.","description":"The token is malformed, unknown or expired. Every case answers the same, so a link can never be probed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"This link is invalid or has expired.","type":"not_found","code":"resource_not_found"}}}},"CreatorPortalRateLimited":{"x-summary":"Too many attempts came from this link or IP address: wait a few minutes and try again.","description":"Too many attempts from this link or IP address (`rate_limited`). Wait a few minutes and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Too many attempts. Try again in a few minutes.","type":"rate_limit_error","code":"rate_limited"}}}},"MoneyForbidden":{"x-summary":"Your credentials are not allowed to move money: use a full-access key or sign in as an owner, admin or billing admin.","description":"Refused (`insufficient_permissions`). One of:\n\n- A restricted API key without the `money` resource group.\n- A profile-scoped API key. Money leaves the whole team's balance, so moving it needs a full-access key or a signed-in session (\"Moving money needs a full-access key or a signed-in session.\").\n- A member or viewer, signed in or through a key they created. Only an owner, admin or billing admin moves money.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Moving money needs a full-access key or a signed-in session.","type":"permission_error","code":"insufficient_permissions"}}}},"AdAccountNotSelected":{"x-summary":"The ad account is not among the connection's selected ad accounts: add it to the selection or use another connection.","description":"Code `ad_account_not_selected`. The connection has selected ad accounts (its ad-account scope, set with the dashboard picker or GET /v1/connect/{platform}/ads with adAccountIds) and the targeted ad account is not among them. The connection may not act on it, even though its token can reach it.\n\n`details` carries `accountId` (the connection), `adAccountId` (the refused ad account) and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (adAccountIds replaces the whole selection, so pass the ids already selected plus this one) or use a connection that has it selected. Connections without a selection keep reaching every ad account their token can manage.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Ad account act_222 is not in the selected ad accounts of connection 6a0000000000000000000001, so requests through this connection cannot act on it.","type":"permission_error","code":"ad_account_not_selected","param":"adAccountId","details":{"accountId":"6a0000000000000000000001","adAccountId":"act_222","selectedAdAccountIds":["act_111"]}}}}},"CatalogPermissionDenied":{"x-summary":"The Meta login lacks catalog permission and reconnecting does not add it: pass `catalogAccountId` for a connection that holds it.","description":"The Meta login behind the account lacks catalog_management (code insufficient_permissions). The permission is pending Meta App Review and is not requested on connect yet, so reconnecting does not add it. Pass catalogAccountId naming a facebook, instagram or metaads connection whose Meta login already holds it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"AccountUnavailable":{"x-summary":"The account was not found or is not accessible: read the current account IDs from the accounts list and retry.","description":"The account or requested resource was not found or is not accessible. An account ID may have been disconnected and removed. Read GET /v1/accounts for current account IDs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Account ID not found. It may have been disconnected and removed. Read GET /v1/accounts for current account IDs.","type":"not_found","code":"account_not_found","param":"accountId"}}}},"AccountDisconnected":{"x-summary":"The account is disconnected: reconnect it, keeping the same account ID, then retry the request.","description":"The account exists but is disconnected (deactivated, or flagged as needing reconnection). Code `account_disconnected`.\n\n`details` names the account (`accountId`, `platform`, `username`) with its `disconnectReason`, `disconnectionType`, `unhealthySince` and `action: reconnect`.\n\nReconnect the account (its accountId stays the same), then retry. The disconnect is also sent as the `account.disconnected` webhook.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"The facebook account \"Acme Fitness\" (6abf72d1fca017c1078db5ab) is disconnected: Facebook tokens expired. Please reconnect your Facebook account. Reconnect this account, then retry with the same accountId.","type":"invalid_request_error","code":"account_disconnected","param":"accountId","details":{"accountId":"6abf72d1fca017c1078db5ab","platform":"facebook","username":"Acme Fitness","disconnectReason":"Facebook tokens expired. Please reconnect your Facebook account.","disconnectionType":"unintentional","unhealthySince":"2026-10-18T08:59:31.000Z","action":"reconnect"}}}}},"AccountConnectionRequired":{"x-summary":"The account is inactive or needs reconnection: reconnect it, then read the accounts list for its current ID before retrying.","description":"The account exists but is inactive or needs reconnection. Reconnect it, then read GET /v1/accounts for its current account ID before retrying. Code: ads_connection_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"This account needs reconnection. Reconnect the account, then read GET /v1/accounts for its current account ID before retrying.","type":"invalid_request_error","code":"ads_connection_required","param":"accountId"}}}},"StoreReconnectRequired":{"x-summary":"The store must re-approve the Zernio app or needs reconnecting: send the merchant to `details.authUrl`.","description":"The store must re-approve the Zernio app (Shopify or Wix), or connect a Webflow site with the Zernio Webflow app, to grant pixel access (code `reconnect_required`). Send the merchant to `details.authUrl`; the account id stays the same. Also returned while the store account itself needs reconnection (code `ads_connection_required`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"The Shopify store acme.myshopify.com has not granted write_pixels, read_customer_events. Send the merchant to details.authUrl to re-approve the Zernio app (the account id stays the same), then retry.","type":"permission_error","code":"reconnect_required","param":"storeAccountId","platform":"shopify","details":{"missingScopes":["write_pixels","read_customer_events"],"authUrl":"https://acme.myshopify.com/admin/oauth/authorize?client_id=..."}}}}},"TemporarilyUnavailable":{"x-summary":"An upstream service is temporarily unavailable: retry after the indicated delay and check a timed-out write before resubmitting it.","description":"An upstream service or database is temporarily unavailable. Retry after the indicated delay. A timed-out write may have completed upstream; check its outcome before resubmitting.","headers":{"Retry-After":{"schema":{"type":"integer","example":5},"description":"Minimum delay in seconds before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Temporary connection issue while reaching an upstream service. Please retry the request.","type":"api_error","code":"temporarily_unavailable"}}}},"UpstreamFailure":{"description":"The platform returned a server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"The platform could not complete the request.","type":"platform_error","code":"platform_api_error"}}}},"IdempotencyKeyInFlight":{"description":"Same Idempotency-Key still processing; retry after a short backoff"},"IdempotencyKeyReused":{"description":"Idempotency-Key reused with a different request"},"BusinessAgentForbidden":{"x-summary":"The Inbox add-on, Business Agent permission or terms are missing: enable the add-on, reconnect WhatsApp, or accept the terms in WhatsApp Manager.","description":"Inbox add-on required, the WhatsApp token lacks the Business Agent permissions (code reconnect_required), or the merchant has not accepted the Meta Business Agent terms in WhatsApp Manager (code business_agent_terms_not_accepted).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"BusinessAgentNotFound":{"description":"Account not found, or no agent exists on the number yet or the referenced item does not exist (code business_agent_not_found).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"BusinessAgentDeleted":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean"}}}}}},"CreatorCampaignForbidden":{"x-summary":"The workspace lacks usage-based billing, the campaign is full, or the key lacks access: switch billing or use a permitted key.","description":"Refused. Code `feature_not_available`: creator campaigns run on usage-based\nbilling and the workspace that owns the campaign is not on it yet (\"Creator campaigns\nrequire usage-based billing...\"; contact support to switch), or the campaign reached\n`caps.maxParticipants` (invites and joins only).\nCode `insufficient_permissions`: a restricted API key without the `creator_campaigns`\nresource group.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Creator campaigns require usage-based billing, which is not enabled for this account yet. Contact support to switch your workspace.","type":"permission_error","code":"feature_not_available"}}}},"CreatorCampaignNotFound":{"x-summary":"The campaign, participant or submission does not exist or is not reachable with this key: check the ID and the key's scope.","description":"The campaign, participant or submission does not exist, belongs to another team, or sits in a profile this key cannot reach (code `resource_not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Campaign not found","type":"not_found","code":"resource_not_found"}}}},"CreatorCampaignConflict":{"x-summary":"The resource state does not allow this action, or the idempotency key is still processing: check the current state and retry later.","description":"The campaign, participant or submission is not in a state that allows this action (code `invalid_resource_state`); the message names the current state. Also returned while the same `Idempotency-Key` is still processing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Cannot move a closed campaign to active","type":"invalid_request_error","code":"invalid_resource_state"}}}},"MailboxPreconditionFailed":{"x-summary":"The account lacks a needed scope or admin approval: reconnect with wider scopes, or send an administrator the consent link.","description":"The connected account cannot serve this request until something outside the request changes. Two codes:\n\n- `account_scope_missing`: the account was connected without the area this endpoint needs (`details.grantedAreas`, `details.missingArea`), or Google reports the grant lacks a permission. Reconnect with a wider `scopes=`.\n- `admin_consent_required` (Microsoft): the tenant requires an administrator's approval. `details.adminConsentUrl` is the Microsoft Entra admin-consent link to hand to one; it opens in a browser with no API key and stays valid for one hour. `GET /v1/connect/microsoft/admin-consent` mints a fresh one.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"EmailSendRefused":{"x-summary":"The email was refused because the mailbox hit its daily cap or a sending cooldown: wait until `retryAfterSeconds` passes and retry.","description":"The send was refused before reaching the provider.\n\n- `email_send_cap_reached`: today's cap for the mailbox is spent. `details.cap` names the limit and `resetsAt`; `retryAfterSeconds` counts to midnight UTC.\n- `rate_limited`: the mailbox is in a sending cooldown, either from a same-body burst to more than 50 recipients in an hour (`details.cap.kind: recipient_burst`) or an earlier trigger. `retryAfterSeconds` says when it lifts, and `account.rate_limited` fired when it started.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"BalanceRequired":{"x-summary":"Balance at $0: top up in Billing to continue.","description":"Balance billing only. The balance is at or below $0, so new pay-per-use is refused: code `insufficient_balance`, or `usage_limit_reached` when the auto-recharge monthly limit kept it there. Top up in Billing. Inbound traffic and calls already connected are never refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"BadRequest":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"x-summary":"The API key is missing or invalid: send a valid key in the Authorization header.","description":"Missing or invalid API key. `code` is `missing_credentials` when no Authorization header was sent and `invalid_credentials` when the key is unknown, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Missing API key. Send it as Authorization: Bearer <your API key>.","type":"authentication_error","code":"missing_credentials","docUrl":"https://docs.zernio.com"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Not found"}}}}}},"AutomationsAdsRequired":{"description":"Ad rules only: your account has no ads access (code `ads_addon_required`). Ads are included on usage-based plans. Event and scheduled automations never get this 403: a boost step without ads access is refused with a 400 at its path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"AutomationInvalid":{"description":"The automation is invalid, or holds something its kind cannot: `details.problems` lists each problem with its JSON path. A few ad rule checks (an unsupported platform, step or metric, a cooldown shorter than the schedule, approvers not on the team) answer with `param` instead.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"details":{"$ref":"#/components/schemas/AutomationProblems"}}}]},"example":{"error":"Ad rules count in whole minutes","code":"invalid_field_value","param":"limits.cooldown","details":{"problems":[{"path":"limits.cooldown","code":"not_supported","message":"Ad rules count in whole minutes"}]}}}}},"AutomationApprovalRefused":{"description":"Code `invalid_resource_state`. Nothing was changed. The request was already approved or rejected, it expired, or it was cancelled when the automation stopped asking for approval.\n\nAlso returned when the automation no longer asks for approval or never does, and when it is acting on the ad account right now (try again in a minute).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"AnalyticsAddonRequired":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Analytics add-on required"},"code":{"type":"string","example":"analytics_addon_required"}}}}}},"ResourceGroupForbidden":{"x-summary":"A restricted key cannot do this: enable the resource group on a new key, or use a full-access key for admin operations.","description":"The API key is a restricted key (zrk_ prefix) and may not perform this operation. Three cases:\n\n1. The operation's resource group (see the operation's x-resource-group) is disabled on the key. Fix: create a key with the group enabled in the dashboard API keys tab and revoke the old one.\n2. The operation is admin-plane (x-resource-group admin-plane: API keys, invites, connected apps, member identity), never grantable to restricted keys. The error reads \"Restricted API keys cannot manage API keys, invites, or member identity.\" Fix: a full-access key or the dashboard, never a new restricted key.\n3. On webhook subscription writes, delivery-log reads and replays, a named event maps to a resource group the key does not hold. A restricted key can never create or edit a subscription broader than itself (a no-messages key cannot subscribe to, test-fire, redeliver or read logs for message.* events).\n","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","commerce","creator_campaigns","money","calendar","files"]}}}}}},"RateLimited":{"x-summary":"The connected account's upstream platform quota is exhausted: wait for the limit to reset before retrying, since repeated calls do not succeed.","description":"The connected account's upstream platform quota is exhausted. Behavior per platform:\n\n- **Reddit:** rate-limits per connected Reddit user (1000 requests per 10-minute window), shared by every operation on that account. Retry after the window resets; repeated calls while exhausted do not succeed and keep the budget spent.\n- **Google Ads:** writes and reports run on one developer token shared by every Google Ads account on Zernio. It holds Standard access (no daily operations cap), so this only happens when Google throttles the token or your ad account.\n- **Google Ads envelope:** `code: rate_limited`, `platform: google`, `details.quotaScope: DEVELOPER` (`ACCOUNT` when it is your own ad account's quota), `details.resetsAt` (ISO instant when Google accepts requests again) and `Retry-After` counting down to it. Retrying earlier cannot succeed.\n- **YouTube Analytics:** reads (channel-insights, demographics, daily-views, video-retention) use the \"Queries per day\" quota of the Google Cloud project the account is connected through, shared with other Zernio customers, so a 429 is not your own volume. Resets at midnight Pacific Time.\n- **YouTube Analytics envelope:** `code: rate_limited`, `platform: google`, `details.quotaExhausted: true`, `details.quotaScope: DEVELOPER`, `details.resetsAt` and `Retry-After` counting down to it. Retrying earlier cannot succeed.\n- **Meta ads:** every Meta throttle (codes 4, 17, 32, 613 and business-use-case codes 80000-80014) returns 429 `rate_limited`, even when Meta answers HTTP 400. `Retry-After` comes from Meta's `x-business-use-case-usage` estimate when sent, else Meta's 60-second minimum (30 seconds for the one-write-per-30-seconds limit on one object).\n- **Pinterest ads:** limits per user and app, per category (ads_read, ads_write, ads_analytics). `Retry-After` comes from Pinterest's `x-ratelimit-reset` when sent, otherwise 60 seconds.\n- **TikTok ads:** limits per app and per endpoint (per second, minute and day), answering overage with code 40100 or code 40002 `OVER_QPS_LIMIT`. Both return 429 `rate_limited` with `platform: tiktok` and `Retry-After: 10`. Space out bulk reads (e.g. one ad at a time per advertiser) instead of retrying at once.\n\n**TikTok Smart+ review read** (`GET /v1/ads/{adId}/tiktok-smart-plus-review`) has its own stricter TikTok quota. After an overage, Zernio answers 429 for that advertiser and connection without calling TikTok for about 60 seconds, then 120, up to 240 while TikTok keeps refusing, each with up to 10% random jitter.\n\nA successful call holds nothing back; the next overage pauses about 60 seconds again. `Retry-After` is the time left. The advertiser-wide read (`GET /v1/ads/tiktok-smart-plus-reviews`) answers 200 with `retryAfterSeconds` and `refreshState` instead. Keep one request in flight per advertiser there.\n","headers":{"Retry-After":{"description":"Seconds remaining until the upstream quota resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"AnalyticsRateLimited":{"x-summary":"Too many requests: wait `Retry-After` seconds, then spread the calls out.","description":"A limit on your request rate was reached: your plan's API limit, or the team's analytics read cap on a 30-second sliding window. `details.scope` names the capped group (`campaign-analytics`, `ad-analytics`, `ads-listings` or `post-analytics`) and is absent for the API limit.\n","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The ceiling of the limit that was reached.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds since epoch) when the next slot frees up.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object","properties":{"currentCount":{"type":"integer"},"limit":{"type":"integer"},"retryAfterSeconds":{"type":"integer"},"scope":{"type":"string","enum":["campaign-analytics","ad-analytics","ads-listings","post-analytics"]},"window":{"type":"string"}}}}},"example":{"error":"Limit of 120 requests per 30 s reached for campaign-analytics reads. Read many campaigns in one request with GET /v1/ads/tree instead of one request each. Please retry after 12 seconds.","details":{"currentCount":121,"limit":120,"retryAfterSeconds":12,"scope":"campaign-analytics","window":"30 s"}}}}},"MetaAdAccountWriteLimited":{"x-summary":"The Meta ad account hit its create limit: wait `Retry-After` seconds, then send creates for that account one at a time.","description":"Meta only (code `rate_limited`). Meta puts a security hold lasting days (code 31, subcode 3858385, \"Please authenticate your account\") on ad accounts that receive bursts of ad writes, and it counts `validateOnly` checks as writes.\n\nCreates here are every request that creates ad objects on the ad account: `POST /v1/ads/create`, `/boost`, `/campaigns`, `/messaging`, `/ctwa` and `/call` (each including `validateOnly`), the three duplicate routes, and a creative rebuilt by `PUT /v1/ads/{adId}` or `PATCH /v1/ads/{adId}/tracking-tags`. One request counts as one create, however many objects it writes.\n\nTo keep integrations out of that hold, Zernio:\n\n- runs creates for one Meta ad account one at a time (a parallel request waits up to 60 seconds for its turn);\n- allows at most 30 creates per ad account in any rolling 5 minutes, `validateOnly` included.\n\nA 429 here means one of the two was hit. `details.adAccountId` names the ad account and `details.reason` says which:\n\n- `ad_account_busy`: another create on the ad account was still running after the 60-second wait (`Retry-After: 15`);\n- `ad_account_write_cap`: the 30 creates in 5 minutes are used up (`Retry-After` counts down to the next free slot).\n\nWait `Retry-After` seconds and send creates for that ad account sequentially. Other ad accounts are not affected.\n","headers":{"Retry-After":{"description":"Seconds to wait before retrying a create on this ad account.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"MetaRateLimited":{"x-summary":"Meta throttled the request: wait the number of seconds in `Retry-After` before retrying.","description":"Meta throttled the request (code `rate_limited`, `platform: meta`). Every Meta throttle returns 429 here, even when Meta itself answers HTTP 400:\n\n- 4, 17 and 32: app, user and page request limits\n- 613: per-object call limits\n- 80000-80014: business-use-case limits per ad account or business (e.g. 80000 ads insights, 80003 custom audiences, 80004 ads management, 80014 catalog batch)\n\nWait `Retry-After` seconds before retrying: Meta's `x-business-use-case-usage` estimate when sent, otherwise Meta's documented 60-second minimum. Business-use-case limits are scoped to one ad account, so other ad accounts are not affected.\n","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PaymentRequired":{"x-summary":"Billing blocked the request: redirect the user to `dashboard_url` to add or verify a card or use the enterprise form.","description":"Payment method or enterprise contract required: the authenticated account hit a billing gate before the connection could proceed. Switch on `reason` to render the right prompt:\n\n- `free_tier_exceeded`: the team has connected more accounts than the free tier allows. Add a payment method to continue (billed per additional connected account).\n- `twitter_passthrough`: connecting an X 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 only the 3rd+.\n- `enterprise_required`: the team's enterprise contract sets a connected-account cap and it has been reached. Self-service teams have NO cap (the $1/account rate continues at any scale). The user already has a card on file; this gate is about contract terms.\n- `card_verification_required`: the card on file was flagged at add time (prepaid, or issued in a different country than the billing address). A one-time verification charge of `details.verification_amount_cents` (USD) is pending; it is credited to the team's usage balance, not a fee.\n\n**What to do:** redirect the end-user to `dashboard_url`.\n\n- `free_tier_exceeded`, `twitter_passthrough`, `card_verification_required`: it opens the Zernio billing page (the add-payment-method drawer, or the verification step). The request succeeds once the card is on file (or verified, or paid).\n- `enterprise_required`: it opens the enterprise contact form (not the billing tab), to adjust the contract's limit.\n","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","card_verification_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/pricing/payment-method-required"},"dashboard_url":{"type":"string","format":"uri","description":"Deep-link to send the end-user to. For\n`free_tier_exceeded` and `twitter_passthrough` this opens\nthe add-payment-method drawer on the Zernio billing page.\nFor `enterprise_required` this is the Zernio enterprise\ncontact page.\n","example":"https://zernio.com/dashboard/billing?add_payment_method=1"},"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."},"verification_amount_cents":{"type":"integer","description":"One-time card verification charge in USD cents, credited to usage. Only set when reason=card_verification_required.","example":1000},"effective_account_limit":{"type":"integer","description":"The negotiated connected-account cap from the\nteam's enterprise contract. Self-service teams\nhave no cap and never receive this reason. Only\nset when reason=enterprise_required.\n","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/pricing/payment-method-required","dashboard_url":"https://zernio.com/dashboard/billing?add_payment_method=1","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/pricing/payment-method-required","dashboard_url":"https://zernio.com/dashboard/billing?add_payment_method=1","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/pricing/payment-method-required","dashboard_url":"https://zernio.com/enterprise","details":{"effective_account_limit":2000,"current_account_count":2000}}}}}}}},"schemas":{"CreatorPortalCampaign":{"type":"object","description":"The campaign as a creator sees it: terms, never the budget.","required":["id","name","brandName","logoUrl","theme","status","platforms","contentRules","startsAt","endsAt","startedAt","currency","economics","maxPostAgeMinutes","holdDays","trackingDays","maxAccountsPerParticipant"],"properties":{"id":{"type":"string","description":"The campaign id, as in a link-recovery URL."},"name":{"type":"string"},"brandName":{"type":"string"},"logoUrl":{"type":["string","null"]},"theme":{"type":["object","null"],"description":"Same keys as the `welcomeTheme` parameter of `GET /v1/connect/{platform}`."},"status":{"type":"string","enum":["draft","active","paused","closed"]},"platforms":{"type":"array","items":{"type":"string"}},"contentRules":{"type":["string","null"]},"startsAt":{"type":["string","null"],"format":"date-time"},"endsAt":{"type":["string","null"],"format":"date-time"},"startedAt":{"type":"string","format":"date-time","description":"Posts published before this moment do not count: `startsAt`, else when the campaign went live."},"currency":{"type":"string"},"economics":{"$ref":"#/components/schemas/CreatorPortalEconomics"},"maxPostAgeMinutes":{"type":["integer","null"],"description":"A post must be submitted within this many minutes of publishing. Null means any age. Either way, only posts published after the campaign started are accepted."},"holdDays":{"type":"integer","description":"Days approved earnings stay owed before they become payable."},"trackingDays":{"type":"integer","description":"Days each submitted post is tracked for views."},"maxAccountsPerParticipant":{"type":["integer","null"],"description":"How many connected accounts can submit posts. Null means no limit."}}},"CreatorPortalEconomics":{"description":"How the campaign pays, without its budget. Amounts in cents. A pool campaign shows the pool size as `poolCents`.","oneOf":[{"type":"object","title":"CPM","required":["type","ratePer1kCents","minViewsToEarn"],"properties":{"type":{"type":"string","enum":["cpm"]},"metric":{"type":"string","enum":["views","engagements"],"description":"What the rate pays on. Missing means views."},"engagementTypes":{"type":"array","items":{"type":"string","enum":["likes","comments","shares","saves"]},"description":"The engagements that count. Missing means all four."},"organicViewsOnly":{"type":"boolean","description":"Only organic views count; views from ads do not."},"ratePer1kCents":{"type":"integer"},"minViewsToEarn":{"type":"integer"},"maxPayoutPerClipCents":{"type":"integer"}}},{"type":"object","title":"Per post","required":["type","perApprovedPostCents"],"properties":{"type":{"type":"string","enum":["per_post"]},"perApprovedPostCents":{"type":"integer"},"maxPostsPerParticipant":{"type":"integer"}}},{"type":"object","title":"Pool","required":["type","poolCents","minViewsToQualify"],"properties":{"type":{"type":"string","enum":["pool"]},"poolCents":{"type":"integer"},"minViewsToQualify":{"type":"integer"},"organicViewsOnly":{"type":"boolean","description":"Only organic views count; views from ads do not."}}}]},"CreatorPortalSubmission":{"type":"object","required":["id","platform","postId","url","status","submittedAt","publishedAt","views","engagements","viewsFromAds","earnedCents","rejectReason","flags","trackingEndsAt"],"properties":{"id":{"type":"string"},"platform":{"type":"string"},"postId":{"type":"string"},"url":{"type":["string","null"]},"status":{"type":"string","enum":["received","tracking","pending_review","approved","rejected","expired","withdrawn"]},"submittedAt":{"type":"string","format":"date-time"},"publishedAt":{"type":["string","null"],"format":"date-time"},"views":{"type":"integer","description":"Latest view count read for the post."},"engagements":{"type":["integer","null"],"description":"The campaign engagement types summed at the latest read. Null until the post is read."},"viewsFromAds":{"type":["integer","null"],"description":"Views that came from ads the creator ran, on YouTube and X. Null where the platform does not report them or before the first read."},"earnedCents":{"type":"integer"},"rejectReason":{"type":["string","null"]},"flags":{"type":"array","description":"Creator-safe flags only. Every other review flag shows as `under_review`.","items":{"type":"string","enum":["unreachable","post_deleted","duplicate_post","under_review"]}},"trackingEndsAt":{"type":["string","null"],"format":"date-time"}}},"CreatorPortalPayoutSetup":{"type":"object","required":["mode","status","country","suggestedCountry","transfers"],"properties":{"mode":{"type":"string","enum":["none","external","treasury"],"description":"How the campaign pays: treasury means through Zernio, so the creator onboards for payouts, which they can do from the moment they join. Earnings wait until it is done."},"status":{"type":"string","enum":["not_started","pending","enabled","not_applicable"]},"country":{"type":["string","null"]},"suggestedCountry":{"type":["string","null"],"description":"The country the request came from, to preselect before payout setup starts. Null once the payout account has a country, and outside treasury mode."},"transfers":{"type":"array","description":"Treasury payouts sent to the creator.","items":{"type":"object","required":["id","amountCents","createdAt"],"properties":{"id":{"type":"string"},"amountCents":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}}}}},"CreatorPortalPayoutEntry":{"type":"object","required":["id","kind","amountCents","fromBucket","toBucket","holdUntil","createdAt"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["accrual","approval","hold_release","adjustment","settling","settlement","reversal","topup","transfer","fee","usage","grant"]},"amountCents":{"type":"integer"},"fromBucket":{"type":["string","null"],"description":"The participant bucket the money left; null when it came from outside the participant."},"toBucket":{"type":["string","null"],"description":"The participant bucket the money entered; null when it left the participant."},"holdUntil":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"CreatorPortalInvite":{"type":"object","required":["kind","campaign"],"properties":{"kind":{"type":"string","enum":["invite"]},"campaign":{"$ref":"#/components/schemas/CreatorPortalCampaign"}}},"CreatorPortalParticipant":{"type":"object","required":["kind","campaign","participant","accounts","submissions","earnings","payouts"],"properties":{"kind":{"type":"string","enum":["participant"]},"campaign":{"$ref":"#/components/schemas/CreatorPortalCampaign"},"participant":{"type":"object","required":["displayName","status","joinedAt"],"properties":{"displayName":{"type":"string"},"status":{"type":"string","enum":["invited","active","suspended","removed"]},"joinedAt":{"type":["string","null"],"format":"date-time"}}},"accounts":{"type":"array","description":"Verified accounts on the campaign's platforms.","items":{"type":"object","required":["id","platform","username","displayName","avatarUrl","counts"],"properties":{"id":{"type":"string","description":"Pass to `DELETE /public/creator-campaigns/{token}/accounts/{accountId}` to remove the account."},"platform":{"type":"string"},"username":{"type":"string"},"displayName":{"type":["string","null"]},"avatarUrl":{"type":["string","null"]},"counts":{"type":"boolean","description":"False for an account connected past `maxAccountsPerParticipant`: posts from it are refused until another account is removed."}}}},"submissions":{"type":"array","description":"The latest 100 submissions.","items":{"$ref":"#/components/schemas/CreatorPortalSubmission"}},"earnings":{"type":"object","required":["accruingCents","owedCents","payableCents","payingCents","paidCents","nextReleaseAt"],"properties":{"accruingCents":{"type":"integer","description":"Earned, not approved yet."},"owedCents":{"type":"integer","description":"Approved, on hold."},"payableCents":{"type":"integer"},"payingCents":{"type":"integer","description":"A payout in flight."},"paidCents":{"type":"integer"},"nextReleaseAt":{"type":["string","null"],"format":"date-time","description":"When the next held amount becomes payable."}}},"payouts":{"$ref":"#/components/schemas/CreatorPortalPayoutSetup"}}},"TreasuryTopup":{"type":"object","properties":{"id":{"type":"string"},"method":{"type":"string","enum":["card","bank_transfer"]},"purpose":{"type":"string","enum":["balance","payout_batch"],"description":"`balance` funds your balance; `payout_batch` is the card payment of one payout batch, which pays its creators directly."},"payoutBatch":{"type":["object","null"],"description":"The payout batch this payment paid for; null for a balance top-up.","properties":{"id":{"type":"string"},"campaignId":{"type":["string","null"]}}},"feeCoveredByZernio":{"type":"boolean","description":"True for a balance top-up (there is no card fee) and a `payout_batch` payment: Zernio pays the Stripe processing fee, so you are credited the whole charge. False on a top-up made before 2026-11-05."},"amountCents":{"type":"integer","description":"The amount you asked for. A top-up credits exactly this and charges it plus tax (taxCents). Top-ups from 2026-11-02 to 2026-11-05 charged a card fee on top and credited what Stripe delivered; older ones charged this amount and credited it minus the fee."},"feeCents":{"type":["integer","null"],"description":"Card fee you paid: 0 when Zernio covers it (feeCoveredByZernio). On an older top-up, the fee Stripe took once paid, the fee charged on top before, or null."},"taxCents":{"type":"integer","description":"Tax charged on top of amountCents once paid (VAT where it applies, since 2026-11-05); 0 before payment, when reverse charged, outside the EU, and on older top-ups."},"chargedCents":{"type":"integer","description":"What your card was charged: amountCents plus taxCents, or amountCents plus the card fee on a top-up from 2026-11-02 to 2026-11-05."},"stripeFeeCents":{"type":["integer","null"],"description":"feeCents once the top-up is paid; null before. Kept for older clients: read feeCents."},"netCents":{"type":["integer","null"],"description":"Amount credited to your balance; null until paid. amountCents when feeCoveredByZernio; on an older top-up, what Stripe delivered."},"status":{"type":"string","enum":["pending","succeeded","failed","expired"],"description":"`pending` until the card is charged (or 3D Secure is finished) and credited. `expired` means it ended unpaid: cancelled, or 3D Secure left unfinished for 30 minutes. Only `pending` counts toward pendingTopupCents."},"createdAt":{"type":"string","format":"date-time"},"succeededAt":{"type":["string","null"],"format":"date-time"},"hasInvoice":{"type":"boolean","description":"The paid payment has an invoice (getTopupInvoice): every balance top-up paid since 2026-11-05 (unless charged without one for a Stripe credit balance), and Checkout payments before 2026-10-29. Every paid payment has a card receipt (getTopupReceipt)."}}},"AutoRecharge":{"type":"object","required":["enabled","belowCents","toCents","monthlyLimitCents","alertBelowCents","disabledReason","retryCount","nextRetryAt","monthRechargedCents"],"properties":{"enabled":{"type":"boolean","description":"Whether auto-recharge is on. Charges happen only when this is true and disabledReason is null."},"belowCents":{"type":"integer","description":"Recharge when the balance drops below this, in cents."},"toCents":{"type":"integer","description":"Recharge back up to this, in cents. The charge is toCents minus the balance, plus tax."},"monthlyLimitCents":{"type":["integer","null"],"description":"Most auto-recharge may add per calendar month (UTC), before tax; null for no limit."},"alertBelowCents":{"type":["integer","null"],"description":"Low-balance email threshold, sent once per drop below it; null for none."},"disabledReason":{"type":["string","null"],"enum":["payment_failed",null],"description":"`payment_failed` after four failed charges in a row. Updating the card clears it."},"retryCount":{"type":"integer","description":"Failed charges in a row; 0 once one goes through."},"nextRetryAt":{"type":["string","null"],"format":"date-time","description":"When a declined recharge is tried again; null when none is waiting."},"monthRechargedCents":{"type":"integer","description":"Auto-recharge top-ups this calendar month (UTC), paid or being paid, before tax."}}},"PayoutBatchItem":{"type":"object","required":["id","participantId","creator","amountCents","feeCents","totalCents","status","failureReason","transferId"],"properties":{"id":{"type":"string"},"participantId":{"type":"string"},"creator":{"type":"object","required":["displayName"],"properties":{"displayName":{"type":"string"}}},"amountCents":{"type":"integer","description":"What the creator receives, in full."},"feeCents":{"type":"integer","description":"Zernio fee on top: 4% with a 50 cent minimum."},"totalCents":{"type":"integer","description":"amountCents plus feeCents."},"status":{"type":"string","enum":["pending","paid","failed","skipped"],"description":"`skipped`: not paid because payout setup was not finished, or the card payment never completed; the amount is payable again. `failed`: Stripe refused the transfer; the amount is payable again."},"failureReason":{"type":["string","null"],"description":"Why the item was not paid, in plain words."},"transferId":{"type":["string","null"],"description":"The treasury transfer that paid this item."}}},"PayoutBatch":{"type":"object","required":["id","campaignId","status","method","amountCents","feeCents","totalCents","items","paidAt","finishedAt","createdAt"],"properties":{"id":{"type":"string"},"campaignId":{"type":["string","null"]},"status":{"type":"string","enum":["awaiting_payment","paying","paid","partially_failed","failed","expired"],"description":"`awaiting_payment` until the card charge succeeds (3D Secure included); `paying` while transfers go out; then `paid`, `partially_failed` (some items failed or were skipped), `failed` (the card was declined, or none paid) or `expired` (the payment was cancelled unpaid, every amount is payable again)."},"method":{"type":"string","enum":["card"]},"amountCents":{"type":"integer","description":"Total the creators receive."},"feeCents":{"type":"integer","description":"Total Zernio fee."},"totalCents":{"type":"integer","description":"The card charge: amountCents plus feeCents."},"items":{"type":"array","items":{"$ref":"#/components/schemas/PayoutBatchItem"}},"paidAt":{"type":["string","null"],"format":"date-time"},"finishedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"TreasuryTransfer":{"type":"object","properties":{"id":{"type":"string"},"payeeId":{"type":"string","minLength":24,"maxLength":24,"description":"24-character payee id"},"payeeName":{"type":["string","null"],"description":"The payee's name when Zernio knows it, for example a creator's display name in one of your creator campaigns; null otherwise"},"destinationType":{"type":"string","enum":["creator","ad_account"]},"amountCents":{"type":"integer","description":"Amount the payee receives, in full"},"feeCents":{"type":"integer","description":"Zernio fee added on top, 4% with a 50 cent minimum"},"totalCents":{"type":"integer","description":"Amount debited from your balance: amountCents plus feeCents"},"currency":{"type":"string"},"reference":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"name":{"type":["string","null"],"description":"What the transfer paid for, when Zernio knows it: the campaign name for a creator campaign payout; null otherwise"}}},"status":{"type":"string","enum":["pending","paid","failed","reversed"]},"failureReason":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}},"TreasuryPayee":{"type":"object","properties":{"id":{"type":"string"},"payeeType":{"type":"string","enum":["creator","ad_account"]},"payeeRef":{"type":"string"},"country":{"type":"string"},"onboardingStatus":{"type":"string","enum":["pending","complete","restricted"]},"detailsSubmitted":{"type":"boolean"},"payoutsEnabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"LedgerAccountSide":{"type":"object","properties":{"scopeType":{"type":"string"},"scopeId":{"type":"string"},"bucket":{"type":"string"}}},"AdLeadConsent":{"type":"object","description":"One custom disclaimer checkbox on a Meta lead form (for example a TCPA call or SMS consent), as Meta returns it in custom_disclaimer_responses.","required":["checkboxKey","isChecked"],"properties":{"checkboxKey":{"type":"string","description":"The checkbox key as Meta returns it: the one set in platformSpecificData.customDisclaimer.checkboxes[].key on POST /v1/ads/lead-forms, or otherwise a key Meta derives from the checkbox text, which can be long and contain spaces and punctuation."},"isChecked":{"type":"boolean"}}},"AdLeadConsents":{"type":"array","items":{"$ref":"#/components/schemas/AdLeadConsent"},"description":"Meta lead forms only: the answer to every custom disclaimer checkbox, required or optional. Empty when the form has none, and may be empty on leads stored before 2026-10-22. LinkedIn leads do not carry the field."},"AdLead":{"type":"object","properties":{"id":{"type":"string","description":"Zernio lead id."},"leadgenId":{"type":"string","description":"Meta lead id. On LinkedIn, the leadFormResponse id."},"formId":{"type":"string"},"formName":{"type":["string","null"]},"accountId":{"type":"string"},"adId":{"type":["string","null"]},"adsetId":{"type":["string","null"]},"campaignId":{"type":["string","null"],"description":"On LinkedIn, this is the LinkedIn Campaign id, which corresponds to platformAdSetId on GET /v1/ads (LinkedIn's Campaign Group is Zernio's campaign)."},"isOrganic":{"type":"boolean"},"createdTime":{"type":["string","null"],"description":"ISO 8601."},"fields":{"type":"object","additionalProperties":{"type":"string"},"description":"Question key → answer. On LinkedIn, the key is the lowercased predefinedField, else the question name, else the numeric questionId; multiple-choice values are option labels (unlike Meta, which returns the option key)."},"fieldData":{"type":"array","items":{"type":"object"},"description":"Raw Meta field_data."},"consents":{"$ref":"#/components/schemas/AdLeadConsents"},"status":{"type":"string","enum":["new","contacted","unreachable","qualified","converted","disqualified"],"description":"Meta leads only. `contacted` is set when the first WhatsApp message of a lead_received workflow is delivered, `unreachable` when it fails or the phone number is not valid."},"statusChangedAt":{"type":["string","null"],"format":"date-time"},"value":{"type":["number","null"]},"currency":{"type":["string","null"]},"contactId":{"type":["string","null"],"description":"The contact a lead_received workflow created or matched for this lead."},"firstContactedAt":{"type":["string","null"],"format":"date-time","description":"When the first WhatsApp message to the lead was delivered."},"conversationId":{"type":["string","null"],"description":"The Inbox conversation a lead_received workflow opened with the lead."},"webhookDeliveredAt":{"type":["string","null"],"format":"date-time","description":"Meta leads only. When the `lead.received` webhook was delivered; null while it has not been."}}},"ConnectHandoffLink":{"type":"object","description":"Only with `handoff=true`: the link to show as a QR code.","properties":{"id":{"type":"string","format":"uuid","description":"Pass to `GET /v1/connect/handoffs/{handoffId}`."},"url":{"type":"string","format":"uri","description":"Short link to encode in the QR code. It opens the welcome screen on the phone."},"expiresAt":{"type":"string","format":"date-time","description":"When `url` stops working (30 minutes)."}}},"ConnectHandoff":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["waiting","opened","connected","failed","expired"]},"platform":{"type":"string"},"accounts":{"type":"array","description":"Filled when `status` is `connected`: every account the connect added (several when the user picked several pages, locations or organizations), each checked to be on the profile the connect was started for and written during this handoff. Empty otherwise.","items":{"type":"object","properties":{"id":{"type":"string","description":"The Zernio account id."},"profileId":{"type":"string"},"username":{"type":"string"}}}},"error":{"type":["object","null"],"description":"Set when `status` is `failed`.","properties":{"code":{"type":"string","description":"The `error` code the flow ended on, as on a redirect_url. `connect_incomplete` when the phone reported no outcome, `connect_unverified` when it reported an account Zernio could not match to this connect."},"message":{"type":["string","null"]},"details":{"type":"object","additionalProperties":{"type":"string"},"description":"The other params the redirect flow appends for that error, such as `is_user_fixable`, `reason`, `dashboard_url`, `request_id` and `stage`. All optional."}}}}},"OAuthApp":{"type":"object","required":["id","platform","label","clientId","scopeAreas","status","accountCount","redirectUri","createdAt"],"properties":{"id":{"type":"string","description":"Pass it as `oauthAppId` on GET /v1/connect/{platform} to connect through this app."},"platform":{"type":"string","description":"The platform the app belongs to, as in GET /v1/connect/{platform}."},"label":{"type":"string"},"clientId":{"type":"string","description":"The client ID (or app ID) of your app on the platform. The secret is never returned."},"scopeAreas":{"type":"array","items":{"type":"string","enum":["posting","analytics","comments","messaging"]},"description":"The permission areas every connect through this app requests. Pick only what your app is approved for on the platform."},"status":{"type":"string","enum":["ok","unchecked","invalid"],"description":"`ok`: the platform accepted the keys at the last check. `unchecked`: the check could not reach a verdict (see lastError). `invalid`: the platform rejected the keys; connects and token refreshes through this app will fail until the secret is rotated."},"lastCheckedAt":{"type":["string","null"],"format":"date-time"},"lastError":{"type":["string","null"]},"accountCount":{"type":"integer","description":"Connected accounts currently running on this app."},"redirectUri":{"type":"string","format":"uri","description":"The OAuth redirect URI to allow in your app's settings on the platform."},"webhook":{"type":["object","null"],"description":"Facebook and Instagram only; null on platforms with nothing to set up. Meta delivers comments and messages to your app's own webhook.\n\nSet this callback URL and verify token on the app's webhook product (Page for Facebook, Instagram for Instagram) and subscribe the listed fields. Zernio checks each delivery against your app secret.\n","required":["callbackUrl","verifyToken","object","fields"],"properties":{"callbackUrl":{"type":"string","format":"uri"},"verifyToken":{"type":"string"},"object":{"$ref":"#/components/schemas/OAuthAppWebhookObject"},"fields":{"type":"array","items":{"type":"string"},"description":"Subscribe the app to these fields."}}},"sharedWebhookUrl":{"type":["string","null"],"format":"uri","description":"TikTok only: set this as the webhook callback URL in your TikTok developer app. TikTok uses it to report when a video finishes publishing; Zernio also checks the publish status itself, so posting works without it. Null on other platforms."},"hasSlackSigningSecret":{"type":"boolean","description":"Slack only: whether the signing secret of your Slack app is saved. Without it Zernio refuses every event sent to `slackEvents.requestUrl`."},"slackEvents":{"type":["object","null"],"description":"Slack only; null on other platforms. Slack delivers messages and mentions to your app's own Request URL.\n\nSave the app's signing secret first (`slackSigningSecret`), then set this Request URL under Event Subscriptions and subscribe the listed bot events. Zernio checks each delivery against that secret.\n","required":["requestUrl","botEvents"],"properties":{"requestUrl":{"type":"string","format":"uri"},"botEvents":{"type":"array","items":{"type":"string"},"description":"Subscribe the app to these bot events."}}},"createdAt":{"type":"string","format":"date-time"}}},"OAuthAppWebhookObject":{"type":"string","enum":["page","instagram"],"description":"The webhook object to configure."},"OAuthAppSetup":{"type":"object","required":["platform","redirectUri","coreScopes","scopeAreas"],"properties":{"platform":{"type":"string"},"redirectUri":{"type":"string","format":"uri","description":"Allow this OAuth redirect URI in your app on the platform."},"coreScopes":{"type":"array","items":{"type":"string"},"description":"Requested on every connect, whatever areas the app enables."},"scopeAreas":{"type":"array","description":"The areas an app on this platform can enable, each with the scopes it requests.","items":{"type":"object","required":["area","scopes"],"properties":{"area":{"type":"string","enum":["posting","analytics","comments","messaging"]},"scopes":{"type":"array","items":{"type":"string"}}}}}}},"ConnectWelcomeScreen":{"type":"object","properties":{"showByDefault":{"type":"boolean"},"brandName":{"type":["string","null"]},"logoUrl":{"type":["string","null"]},"theme":{"type":["object","null"],"description":"Same keys as the `welcomeTheme` parameter of `GET /v1/connect/{platform}`."}},"example":{"showByDefault":true,"brandName":"Acme","logoUrl":"https://acme.com/logo.png","theme":{"primaryColor":"#1D4ED8","cornerRadius":12}}},"AnalyticsDashboardTotals":{"type":"object","properties":{"impressions":{"type":"integer"},"reach":{"type":"integer"},"likes":{"type":"integer"},"comments":{"type":"integer"},"shares":{"type":"integer"},"saves":{"type":"integer"},"clicks":{"type":"integer"},"views":{"type":"integer"},"engagementRate":{"type":"number","description":"Percentage. Likes, comments, shares and saves over impressions, pooled per platform (reach, then views, when a platform has no impressions)."}}},"AnalyticsDashboardFollowers":{"type":"object","properties":{"current":{"type":"integer","description":"Live follower count when the window includes today, otherwise the count the window ended on."},"gained":{"type":"integer","description":"Last minus first follower snapshot inside the window. Can be negative."},"byAccount":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string"},"current":{"type":"integer"},"gained":{"type":"integer"}}}}}},"AnalyticsDashboardPost":{"type":"object","properties":{"postId":{"type":"string"},"platform":{"type":"string"},"publishedAt":{"type":"string","format":"date-time"},"metrics":{"type":"object","description":"Lifetime metrics of the post on this platform.","properties":{"impressions":{"type":"integer"},"reach":{"type":"integer"},"likes":{"type":"integer"},"comments":{"type":"integer"},"shares":{"type":"integer"},"saves":{"type":"integer"},"clicks":{"type":"integer"},"views":{"type":"integer"},"engagementRate":{"type":"number"}}}}},"BrandedCallingContact":{"type":"object","required":["firstName","lastName","email","phoneNumber"],"properties":{"firstName":{"type":"string","maxLength":100},"lastName":{"type":"string","maxLength":100},"email":{"type":"string","format":"email"},"jobTitle":{"type":"string","maxLength":100,"description":"Required on organizationContact."},"phoneNumber":{"type":"string","description":"E.164 with a leading +."}}},"BrandedCallingAddress":{"type":"object","required":["streetAddress","city","administrativeArea","postalCode","country"],"properties":{"streetAddress":{"type":"string","maxLength":255},"extendedAddress":{"type":"string","maxLength":255},"city":{"type":"string","maxLength":100},"administrativeArea":{"type":"string","description":"State or province code (IL, ON)."},"postalCode":{"type":"string","maxLength":20},"country":{"type":"string","description":"ISO 3166-1 alpha-2 (US or CA)."}}},"BrandedCallingReference":{"type":"object","required":["fullName","phoneNumber","email","timezone"],"description":"A person the carrier vetting team phones to confirm the business. Business references are senior contacts at a vendor, partner or client; the financial reference is a CPA or a bank contact. Calls are placed in the reference's local 8am-9pm window.","properties":{"fullName":{"type":"string","maxLength":255},"jobTitle":{"type":"string","maxLength":255},"organization":{"type":"string","maxLength":255},"relationshipToRegistrant":{"type":"string","maxLength":255},"phoneNumber":{"type":"string","description":"E.164 with a leading +."},"email":{"type":"string","format":"email"},"timezone":{"type":"string","description":"IANA timezone id, e.g. America/New_York."}}},"BrandedCallingReferences":{"type":"object","required":["business","financial"],"properties":{"business":{"type":"array","minItems":2,"maxItems":2,"items":{"$ref":"#/components/schemas/BrandedCallingReference"}},"financial":{"$ref":"#/components/schemas/BrandedCallingReference"}}},"BrandedCallingEnterprise":{"type":"object","properties":{"id":{"type":"string"},"legalName":{"type":"string"},"doingBusinessAs":{"type":"string"},"organizationType":{"type":"string","enum":["commercial","government","non_profit"]},"organizationLegalType":{"type":"string","enum":["corporation","llc","partnership","nonprofit","other"]},"countryCode":{"type":"string","enum":["US","CA"]},"jurisdictionOfIncorporation":{"type":"string"},"website":{"type":"string"},"feinLast4":{"type":"string","description":"Last four digits of the tax id; the full id is never returned."},"industry":{"type":"string"},"numberOfEmployees":{"type":"string","enum":["1-10","11-50","51-200","201-500","501-2000","2001-10000","10001+"]},"organizationContact":{"$ref":"#/components/schemas/BrandedCallingContact"},"billingContact":{"$ref":"#/components/schemas/BrandedCallingContact"},"physicalAddress":{"$ref":"#/components/schemas/BrandedCallingAddress"},"billingAddress":{"$ref":"#/components/schemas/BrandedCallingAddress"},"registered":{"type":"boolean","description":"True once the business exists at the carrier (happens when its first identity passes review)."},"createdAt":{"type":["string","null"],"format":"date-time"}}},"BrandedCallingIdentityNumber":{"type":"object","properties":{"phoneNumberId":{"type":"string"},"phoneNumber":{"type":"string"},"status":{"type":"string","enum":["submitted","in_review","verified","unsuccessful","suspended","expired","permanently_rejected"],"description":"verified = the identity shows on calls from this number. permanently_rejected cannot be attached again anywhere."},"rejectionReason":{"type":["object","null"],"properties":{"code":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"message":{"type":["string","null"]}}},"verifiedAt":{"type":["string","null"],"format":"date-time"},"addedAt":{"type":["string","null"],"format":"date-time"}}},"BrandedCallingIdentity":{"type":"object","properties":{"id":{"type":"string"},"enterpriseId":{"type":"string"},"displayName":{"type":"string","maxLength":35},"callReasons":{"type":"array","items":{"type":"string","maxLength":64}},"callReasonsPreApproved":{"type":"boolean","description":"Every call reason matches the carrier catalogue (GET /v1/branded-calling/call-reasons); anything else is vetted by hand and takes longer."},"logoUrl":{"type":["string","null"],"description":"The image you sent. Zernio hosts the 256x256 BMP the carriers require."},"authorizer":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"}}},"references":{"$ref":"#/components/schemas/BrandedCallingReferences"},"status":{"type":"string","enum":["requested","changes_requested","rejected","pending_email_verification","in_review","verified","suspended","expired","permanently_rejected"],"description":"Verification status:\n\n- requested: in Zernio review\n- changes_requested: answer the review (PATCH)\n- pending_email_verification: confirm the code emailed to the authorizer\n- in_review: with the carrier vetting team\n- verified: attach numbers\n- rejected: fix and PATCH to resubmit\n- suspended: an infringement claim is open\n- expired: the yearly verification lapsed\n- permanently_rejected: terminal\n"},"rejectionReasons":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"message":{"type":["string","null"],"description":"Free-text note from the vetting team, on the first entry only."}}}},"reviewNote":{"type":["string","null"],"description":"The open change request, as text."},"reviewRequest":{"type":["object","null"],"description":"The open change request as points; answer each by id in reviewAnswers on PATCH.","properties":{"id":{"type":"string"},"intro":{"type":"string"},"points":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"answer":{"type":"string","enum":["text","link","file","link_or_file"]}}}}}},"emailVerifiedAt":{"type":["string","null"],"format":"date-time"},"submittedAt":{"type":["string","null"],"format":"date-time"},"verifiedAt":{"type":["string","null"],"format":"date-time"},"expiringAt":{"type":["string","null"],"format":"date-time","description":"Verification lasts one year; Zernio resubmits 30 days before this date."},"numbers":{"type":"array","items":{"$ref":"#/components/schemas/BrandedCallingIdentityNumber"}},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}}},"RcsBrandInput":{"type":"object","required":["displayName","legalName","legalEntityType","organizationType","websiteUrl","taxId","address","contact"],"properties":{"displayName":{"type":"string","maxLength":100},"legalName":{"type":"string","maxLength":100,"description":"Exactly as on IRS records."},"legalEntityType":{"type":"string","enum":["LIMITED_LIABILITY_COMPANY","SOLE_PROPRIETORSHIP","PARTNERSHIP","CORPORATION","S_CORPORATION"]},"organizationType":{"type":"string","enum":["PRIVATE_PROFIT","PUBLIC_PROFIT","NON_PROFIT","GOVERNMENT"]},"websiteUrl":{"type":"string","format":"uri"},"taxId":{"type":"string","description":"US: the EIN, 9 digits, optionally NN-NNNNNNN. Elsewhere: the national tax or company registration id."},"stockSymbol":{"type":"string","description":"EXCHANGE:SYMBOL. Required for PUBLIC_PROFIT."},"address":{"type":"object","required":["line1","city","postalCode","country"],"properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string","description":"Required in the US."},"postalCode":{"type":"string"},"country":{"type":"string","enum":["US","GB","AT","BD","BR","CD","DE","ES","FR","IN","IT","MX","NG","NL","NO","PT","SE","SG","ZA"],"description":"ISO 3166-1 alpha-2. Sets the launch market of agents under this brand. Spain (ES) is accepted but launches are paused at the carriers."}}},"contact":{"type":"object","required":["firstName","lastName","email","phone"],"properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"title":{"type":"string"},"email":{"type":"string","format":"email","description":"A personal address on the company domain; free-mail and group addresses (info@, support@) are rejected by the carriers."},"phone":{"type":"string","description":"E.164"}}}}},"RcsBrand":{"allOf":[{"$ref":"#/components/schemas/RcsBrandInput"},{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["draft","vetting","verified","rejected"],"description":"draft = not filed yet (still editable)."},"createdAt":{"type":"string","format":"date-time"}}}]},"RcsAgentProfile":{"type":"object","required":["description","logoUrl","heroUrl","brandColor","privacyPolicyUrl","termsUrl"],"description":"The agent's public profile. At least one of phone, website or email is required.","properties":{"description":{"type":"string","maxLength":100},"logoUrl":{"type":"string","format":"uri","description":"224x224, max 50 KB. Upload any image through POST /v1/rcs/assets to get a compliant URL."},"heroUrl":{"type":"string","format":"uri","description":"Banner, 1440x448, max 200 KB. Upload through POST /v1/rcs/assets."},"brandColor":{"type":"string","description":"Hex colour, e.g. #1A73E8. Needs 4.5:1 contrast against white."},"privacyPolicyUrl":{"type":"string","format":"uri"},"termsUrl":{"type":"string","format":"uri"},"phone":{"type":"object","required":["number","label"],"properties":{"number":{"type":"string","description":"E.164"},"label":{"type":"string","maxLength":25}}},"website":{"type":"object","required":["url","label"],"properties":{"url":{"type":"string","format":"uri"},"label":{"type":"string","maxLength":25}}},"email":{"type":"object","required":["address","label"],"properties":{"address":{"type":"string","format":"email"},"label":{"type":"string","maxLength":25}}}}},"RcsLaunchRequest":{"type":"object","required":["companyOverview","agentOverview","interactions","messageExamples","consent","testVideoUrl"],"properties":{"companyOverview":{"type":"string","maxLength":2000},"agentOverview":{"type":"string","maxLength":2000},"interactions":{"type":"array","minItems":1,"items":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["TRANSACTIONAL_UPDATES","CUSTOMER_SUPPORT","LOYALTY_OR_REWARD","MARKETING_OR_PROMOTIONAL","ACCOUNT_ALERTS","TWO_WAY_CONVERSATION","OTHER"]},"description":{"type":"string","description":"Required when type is OTHER."}}}},"messageExamples":{"type":"array","minItems":3,"maxItems":10,"items":{"type":"string","maxLength":2000}},"consent":{"type":"object","required":["optInMethods","callToAction","doubleOptIn","optInMessage","helpResponse","optOutResponse"],"properties":{"optInMethods":{"type":"array","minItems":1,"items":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["SMS","WEBSITE","MOBILE_APP","QR_CODE","SALE_POINT","OTHER"]},"description":{"type":"string","description":"Required when type is OTHER."}}}},"callToAction":{"type":"string","description":"The opt-in wording people agree to."},"callToActionUrl":{"type":"string","format":"uri","description":"Required for WEBSITE opt-in."},"callToActionMediaUrl":{"type":"string","format":"uri","description":"Screenshot of the opt-in. Required for WEBSITE and MOBILE_APP opt-in."},"doubleOptIn":{"type":"boolean"},"doubleOptInMessage":{"type":"string","description":"Required when doubleOptIn is true."},"optInMessage":{"type":"string"},"helpResponse":{"type":"string"},"optOutResponse":{"type":"string"}}},"testVideoUrl":{"type":"string","format":"uri","description":"Public video of a test phone sending START, STOP and HELP plus one example conversation."},"additionalInformation":{"type":"string","maxLength":2000}}},"RcsCarrierApproval":{"type":"object","properties":{"approvalId":{"type":"string"},"scope":{"type":"string","enum":["carrier","hub","bot"]},"status":{"type":"string","enum":["PENDING","SUBMITTED","APPROVED","REJECTED"]},"carrier":{"type":["string","null"]},"approvedAt":{"type":["string","null"],"format":"date-time"},"rejectedReason":{"type":["string","null"]}}},"RcsTestDevice":{"type":"object","properties":{"testDeviceId":{"type":"string"},"phoneNumber":{"type":"string"},"inviteStatus":{"type":"string","enum":["PENDING","ACCEPTED","DECLINED"],"description":"The phone must accept the invite in its messaging app before it receives messages."}}},"RcsAgent":{"type":"object","properties":{"id":{"type":"string"},"profileId":{"type":"string"},"accountId":{"type":["string","null"],"description":"The rcs inbox account, created once the agent exists with the carriers."},"country":{"type":"string","description":"Launch market (ISO 3166-1 alpha-2). US agents run through the carriers automatically; other markets are filed by our team and skip the testing and launch_review steps (send the launch request while the agent is still in review)."},"status":{"type":"string","enum":["requested","changes_requested","brand_vetting","agent_review","testing","launch_review","launching","live","rejected","deactivated"]},"displayName":{"type":"string","maxLength":40},"useCase":{"type":"string","enum":["MULTI_USE","PROMOTIONAL","TRANSACTIONAL","OTP"]},"profile":{"$ref":"#/components/schemas/RcsAgentProfile"},"brand":{"oneOf":[{"$ref":"#/components/schemas/RcsBrand"},{"type":"null"}]},"launchRequest":{"oneOf":[{"$ref":"#/components/schemas/RcsLaunchRequest"},{"type":"null"}]},"carrierApprovals":{"type":"array","items":{"$ref":"#/components/schemas/RcsCarrierApproval"}},"testDevices":{"type":"array","items":{"$ref":"#/components/schemas/RcsTestDevice"}},"smsFallbackFrom":{"type":["string","null"]},"reviewNote":{"type":["string","null"],"description":"Our note while status is changes_requested."},"declineReason":{"type":["string","null"]},"requestedAt":{"type":["string","null"],"format":"date-time"},"submittedAt":{"type":["string","null"],"format":"date-time"},"liveAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"RcsSuggestion":{"description":"A tappable chip. Labels are max 25 characters. postbackData (max 2048) comes back unchanged in message.received metadata as postbackPayload when tapped; defaults to the label. Any string works, JSON included: values outside A-Z a-z 0-9 - _ . are encoded on the wire and decoded for you.","oneOf":[{"type":"object","required":["type","text"],"properties":{"type":{"type":"string","enum":["reply"]},"text":{"type":"string","maxLength":25},"postbackData":{"type":"string"}}},{"type":"object","required":["type","text","phoneNumber"],"properties":{"type":{"type":"string","enum":["dial"]},"text":{"type":"string","maxLength":25},"phoneNumber":{"type":"string","description":"E.164"},"postbackData":{"type":"string"}}},{"type":"object","required":["type","text","url"],"properties":{"type":{"type":"string","enum":["openUrl"]},"text":{"type":"string","maxLength":25},"url":{"type":"string","format":"uri"},"application":{"type":"string","enum":["BROWSER","WEBVIEW"],"default":"BROWSER"},"webviewViewMode":{"type":"string","enum":["FULL","HALF","TALL"],"default":"FULL"},"postbackData":{"type":"string"}}},{"type":"object","required":["type","text"],"description":"Needs latitude + longitude, or a query.","properties":{"type":{"type":"string","enum":["viewLocation"]},"text":{"type":"string","maxLength":25},"latitude":{"type":"number"},"longitude":{"type":"number"},"query":{"type":"string"},"label":{"type":"string"},"postbackData":{"type":"string"}}},{"type":"object","required":["type","text"],"properties":{"type":{"type":"string","enum":["shareLocation"]},"text":{"type":"string","maxLength":25},"postbackData":{"type":"string"}}},{"type":"object","required":["type","text","startTime","endTime","title"],"properties":{"type":{"type":"string","enum":["calendarEvent"]},"text":{"type":"string","maxLength":25},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"title":{"type":"string","maxLength":100},"description":{"type":"string","maxLength":500},"postbackData":{"type":"string"}}}]},"RcsMedia":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Public image or video URL."},"thumbnailUrl":{"type":"string","format":"uri","description":"Max 100 KB."},"height":{"type":"string","enum":["SHORT","MEDIUM","TALL"],"default":"MEDIUM"}}},"RcsCard":{"type":"object","description":"Needs a title, description or media.","properties":{"title":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":2000},"media":{"$ref":"#/components/schemas/RcsMedia"},"suggestions":{"type":"array","maxItems":4,"items":{"$ref":"#/components/schemas/RcsSuggestion"}}}},"RcsContent":{"description":"Message content. `suggestions` (max 11) render as chips under the message.","oneOf":[{"type":"object","required":["type","text"],"properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string","maxLength":3072},"suggestions":{"type":"array","maxItems":11,"items":{"$ref":"#/components/schemas/RcsSuggestion"}}}},{"type":"object","required":["type","media"],"properties":{"type":{"type":"string","enum":["media"]},"media":{"$ref":"#/components/schemas/RcsMedia"},"suggestions":{"type":"array","maxItems":11,"items":{"$ref":"#/components/schemas/RcsSuggestion"}}}},{"type":"object","required":["type","card"],"properties":{"type":{"type":"string","enum":["card"]},"card":{"$ref":"#/components/schemas/RcsCard"},"orientation":{"type":"string","enum":["VERTICAL","HORIZONTAL"],"default":"VERTICAL"},"thumbnailAlignment":{"type":"string","enum":["LEFT","RIGHT"],"default":"LEFT"},"suggestions":{"type":"array","maxItems":11,"items":{"$ref":"#/components/schemas/RcsSuggestion"}}}},{"type":"object","required":["type","cards"],"properties":{"type":{"type":"string","enum":["carousel"]},"cards":{"type":"array","minItems":2,"maxItems":10,"items":{"$ref":"#/components/schemas/RcsCard"}},"cardWidth":{"type":"string","enum":["SMALL","MEDIUM"],"default":"MEDIUM"},"suggestions":{"type":"array","maxItems":11,"items":{"$ref":"#/components/schemas/RcsSuggestion"}}}}]},"RcsCapability":{"type":"object","properties":{"phoneNumber":{"type":"string"},"rcsCapable":{"type":"boolean"},"features":{"type":"array","items":{"type":"string"},"description":"e.g. RICHCARD_STANDALONE, RICHCARD_CAROUSEL, ACTION_OPEN_URL, ACTION_DIAL. Absent when not capable."}}},"FeedbackReceipt":{"type":"object","properties":{"id":{"type":"string","description":"Feedback id. Quote it if you follow up with support."},"status":{"type":"string","enum":["received"]},"duplicate":{"type":"boolean","description":"True when this matched a submission with the same summary from the last 24 hours."}}},"SmsRegistrationReviewRequest":{"type":"object","description":"An open change request written as points. Answer each point with POST /v1/sms/registrations/{id}/respond: `answer` says what each point needs (text, a link, a hosted document, or a link or a document).","properties":{"id":{"type":"string","description":"Changes with every request. Send it back as `requestId` when answering, so a reply to a replaced request is refused (409) instead of filed under the new points."},"intro":{"type":"string","description":"Context from the reviewer, e.g. what was already fixed on our side."},"points":{"type":"array","items":{"type":"object","required":["id","title","detail","answer"],"properties":{"id":{"type":"string","description":"Point id to send back in `answers[].pointId`."},"title":{"type":"string"},"detail":{"type":"string","description":"What exactly is needed."},"answer":{"type":"string","enum":["text","link","file","link_or_file"]}}}}}},"MetaProductCatalog":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"vertical":{"type":["string","null"],"description":"Catalog vertical as Meta reports it (e.g. commerce, services, vehicles, hotels)"},"productCount":{"type":"integer"},"businessId":{"type":["string","null"]}}},"MetaCatalogProductInput":{"type":"object","description":"One product shape for single and bulk calls. Money is in major units (12.99); Zernio converts to what Meta wants.","properties":{"retailerId":{"type":"string","maxLength":100,"description":"Your SKU; unique inside the catalog"},"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":9999},"url":{"type":"string","format":"uri","description":"Product page"},"imageUrl":{"type":"string","format":"uri"},"additionalImageUrls":{"type":"array","maxItems":20,"items":{"type":"string","format":"uri"}},"price":{"type":"number","description":"Major units, e.g. 12.99"},"currency":{"type":"string","description":"ISO 4217, e.g. EUR"},"salePrice":{"type":"number"},"salePriceStartDate":{"type":"string","description":"ISO 8601"},"salePriceEndDate":{"type":"string","description":"ISO 8601"},"availability":{"type":"string","enum":["in stock","out of stock","preorder","available for order","discontinued","pending"]},"condition":{"type":"string","enum":["new","refurbished","used"]},"brand":{"type":"string","maxLength":100},"category":{"type":"string","maxLength":250},"googleProductCategory":{"type":"string","maxLength":250},"productType":{"type":"string","maxLength":750},"gtin":{"type":"string","maxLength":50},"mpn":{"type":"string","maxLength":100},"inventory":{"type":"integer","minimum":0},"visibility":{"type":"string","enum":["published","staging"]},"color":{"type":"string","maxLength":200},"size":{"type":"string","maxLength":200},"gender":{"type":"string","enum":["female","male","unisex"]},"material":{"type":"string","maxLength":200},"pattern":{"type":"string","maxLength":100},"customLabel0":{"type":"string","maxLength":100},"customLabel1":{"type":"string","maxLength":100},"customLabel2":{"type":"string","maxLength":100},"customLabel3":{"type":"string","maxLength":100},"customLabel4":{"type":"string","maxLength":100}}},"MetaCatalogProduct":{"type":"object","properties":{"id":{"type":"string","description":"Meta product item ID (use in the product endpoints)"},"retailerId":{"type":["string","null"]},"name":{"type":"string"},"description":{"type":["string","null"]},"url":{"type":["string","null"]},"imageUrl":{"type":["string","null"]},"additionalImageUrls":{"type":"array","items":{"type":"string"}},"price":{"type":["string","null"],"description":"Formatted by Meta, e.g. \"€49.90\""},"salePrice":{"type":["string","null"]},"currency":{"type":["string","null"]},"availability":{"type":["string","null"]},"condition":{"type":["string","null"]},"brand":{"type":["string","null"]},"category":{"type":["string","null"]},"productType":{"type":["string","null"]},"gtin":{"type":["string","null"]},"inventory":{"type":["integer","null"]},"visibility":{"type":["string","null"]},"color":{"type":["string","null"]},"size":{"type":["string","null"]},"gender":{"type":["string","null"]},"material":{"type":["string","null"]},"pattern":{"type":["string","null"]},"customLabels":{"type":"array","items":{"type":["string","null"]},"description":"custom_label_0 to custom_label_4"},"reviewStatus":{"type":["string","null"],"description":"Meta's commerce review status (approved, rejected, pending, ...)"},"reviewRejectionReasons":{"type":"array","items":{"type":"string"}}}},"MetaProductFeed":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"productCount":{"type":"integer"},"schedule":{"type":["object","null"],"properties":{"interval":{"type":"string"},"url":{"type":"string"},"hour":{"type":["integer","null"]},"dayOfWeek":{"type":["string","null"]}}},"createdTime":{"type":["string","null"]},"latestUpload":{"oneOf":[{"$ref":"#/components/schemas/MetaFeedUpload"},{"type":"null"}]}}},"MetaFeedUpload":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":["string","null"]},"startTime":{"type":["string","null"]},"endTime":{"type":["string","null"]},"errorCount":{"type":"integer"},"warningCount":{"type":"integer"},"itemsDetected":{"type":"integer"},"itemsDeleted":{"type":"integer"}}},"MetaProductSet":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"productCount":{"type":"integer"},"filter":{"type":["object","null"],"additionalProperties":true}}},"WhatsAppCommerceSettings":{"type":"object","properties":{"isCartEnabled":{"type":"boolean"},"isCatalogVisible":{"type":"boolean"}}},"WhatsAppTemplateLookupError":{"type":"object","required":["error","type","code","platform","details"],"properties":{"error":{"type":"string"},"type":{"type":"string","enum":["platform_error"]},"code":{"type":"string","enum":["platform_api_error"]},"platform":{"type":"string","enum":["whatsapp"]},"platformError":{"type":"object","description":"Sanitized Meta lookup error fields, present when Meta returned them.","properties":{"code":{"type":"integer"},"message":{"type":"string"},"error_data":{"type":"object","properties":{"details":{"type":"string"}}}}},"details":{"type":"object","required":["phase","endpoint"],"properties":{"phase":{"type":"string","enum":["template_lookup"]},"endpoint":{"type":"string","description":"Meta endpoint path without query parameters or access tokens"},"upstreamStatus":{"type":"integer"},"providerHeaders":{"type":"object","description":"Safe provider headers retained from the lookup response.","properties":{"retry-after":{"type":"string"},"x-app-usage":{"type":"string"},"x-business-use-case-usage":{"type":"string"}},"additionalProperties":false}}}}},"AdAppliedDefaults":{"type":"object","description":"What the create filled in for fields the request left out. Empty when every field was sent. A passing validateOnly returns it too, so a dry run previews these values before anything is created.","properties":{"name":{"type":"string","description":"Sent when `name` was omitted: `Ad <YYYY-MM-DD HH:MM:SS>` in UTC."},"goal":{"type":"string","description":"Sent when `goal` was omitted: the goal Zernio inferred.\n\n- `lead_generation`: with a `leadGenFormId`.\n- `app_promotion`: when `promotedObject` names an app.\n- `conversions`: with `promotedObject.pixelId` and `customEventType`.\n- `traffic`: when the ad has a link (`linkUrl`, a carousel card, `creatives[].linkUrl`, `dynamicCreative.linkUrls` or a LinkedIn carousel card).\n- `engagement`: otherwise.\n\nEach applies only when the platform offers it, falling back to `engagement`, then `awareness`, then the platform's first goal. Never inferred with `existingCampaignId`, `smartPlus` or the LinkedIn spotlight, follower and jobs formats: those still return 400 without `goal`."},"budgetType":{"type":"string","enum":["daily"],"description":"Sent when `budgetAmount` came without `budgetType`."},"endDate":{"type":"string","description":"Sent when a lifetime budget had no `endDate`: 7 days after the start. A daily budget never gets one and runs until paused.\n\n- A start with an offset (or no start) gets a UTC instant.\n- An offset-less start gets an offset-less end, read in the ad account timezone like the start.\n- A date-only start gets the date 6 days later, which runs to 23:59:59."},"countries":{"type":"array","items":{"type":"string"},"description":"Sent when the request sent no countries and the ad gets the long-standing United States default. Not sent on attach, Google Performance Max or Demand Gen, or a Google ad group joining `existingCampaignId`, which keep their own geo."}}},"AdTracking":{"type":"object","description":"Ad tracking. Meta, plus `urlTags` on ChatGPT (OpenAI) and `pixelId` on Reddit.\n\n**Meta**: attaches pixel measurement to the ad regardless of the optimization goal (the \"Website events\" tracking row in Ads Manager).\n\n- `pixelId` becomes the ad's `tracking_specs` (offsite_conversion + fb_pixel).\n- `urlTags` is stored on the new creative as `url_tags` and retained on the ad for compatibility.\n- Applied on the legacy single-creative shape, every ad of the multi-creative shape, and the attach shape.\n- Tracking lives on the AD object and is not inherited from the ad set, so pass it on EVERY attach call that should carry the pixel.\n\n**ChatGPT (OpenAI)**: `urlTags` becomes the ad's `landing_page_configuration.query_string_template`, which OpenAI appends to `linkUrl` on click.\n\n**Reddit**: `pixelId` picks the pixel of the new ad group, like `promotedObject.pixelId` (which wins when both are sent).\n","properties":{"pixelId":{"type":"string","description":"Meta Pixel ID to attach for offsite-conversion measurement, or the Reddit pixel of the new ad group."},"urlTags":{"type":"array","description":"Click-URL params.\n\n- Meta: stored on the creative as `url_tags` and returned by GET /v1/ads/{adId}/tracking-tags. Dynamic macros ({{ad.id}}, {{campaign.id}}, {{placement}}, ...) are sent through unescaped so Meta expands them; every other character is percent-encoded. App-promotion linkUrl stays byte-identical to promotedObject.objectStoreUrl.\n- ChatGPT (OpenAI): the same encoding, with OpenAI's macros `{campaign_id}`, `{ad_group_id}`, `{ad_id}` and `{oppref}` (click id) passed through raw. OpenAI expands macros here, not inside `linkUrl`.\n","items":{"type":"object","required":["key","value"],"properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"zernioTag":{"type":"boolean","default":false,"description":"POST /v1/ads/create on Meta and Google only. Opt-in: set `true` and the ad carries `zrn=<platform ad id>` on its landing URL, so orders and events tied to the landing URL map back to the ad.\n\n- **Meta:** `{ key: zrn, value: '{{ad.id}}' }` is appended after your `urlTags`, which are sent unchanged; a `zrn` key you send yourself is kept. Skipped for lead forms, call ads, `existingCreativeId` and app promotion.\n- **Google (Display and Search):** the ad's `final_url_suffix` is set to `zrn={creative}` only when the ad inherits no suffix from its ad group, campaign or account. Otherwise the ad is left untouched (your suffix keeps applying) and attribution uses the click's `gclid`.\n- If the inherited suffix cannot be read or Google rejects the tag, the ad is created untagged.\n\nExisting ads are never changed. Omitted or `false` creates the ad with no Zernio tag.\n"}}},"MetaLeadForm":{"type":"object","description":"A Meta Lead Gen form as Graph returns it, in Meta's own snake_case. Read through GET /v1/ads/lead-forms/{formId}.\n\nEvery setting POST /v1/ads/lead-forms writes is present here, so you can diff a form against what was created and detect drift from edits made in Meta's form builder.\n\nA compound field is omitted entirely when the form has no value for it, and `fields` narrows the selection.\n","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","description":"One of ACTIVE, ARCHIVED, DELETED or DRAFT."},"locale":{"type":"string","example":"en_US"},"created_time":{"type":"string","format":"date-time"},"page_id":{"type":"string","description":"Owning Facebook Page. A form on any other Page is a 404, whether read or archived."},"leads_count":{"type":"integer"},"organic_leads_count":{"type":"integer"},"expired_leads_count":{"type":"integer","description":"Leads Meta has aged out of the retention window."},"privacy_policy_url":{"type":"string","format":"uri"},"follow_up_action_url":{"type":"string","format":"uri"},"follow_up_action_text":{"type":"string"},"question_page_custom_headline":{"type":"string"},"is_optimized_for_quality":{"type":"boolean"},"block_display_for_non_targeted_viewer":{"type":"boolean"},"allow_organic_lead":{"type":"boolean","description":"Whether the form can also be submitted from an organic Page post."},"tracking_parameters":{"type":"array","description":"Custom key/value pairs attached to every lead of this form.","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"legal_content":{"type":"object","description":"Privacy policy and custom disclaimer as Meta stores them.","properties":{"id":{"type":"string"},"privacy_policy":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"link_text":{"type":"string"}}},"custom_disclaimer":{"type":"object","description":"Set in Meta form builder only; there is no create parameter for it."}}},"context_card":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"style":{"type":"string","enum":["LIST_STYLE","PARAGRAPH_STYLE"]},"content":{"type":"array","items":{"type":"string"}},"button_text":{"type":"string"},"cover_photo":{"type":"object","properties":{"id":{"type":"string"}}}}},"thank_you_page":{"type":"object","description":"The form's single ending page, mirroring the thankYou* create fields. Meta has exactly one per form; there is no multiple-ending-page API (thank_you_pages and ending_pages are not Graph fields).\n","properties":{"id":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"},"button_text":{"type":"string"},"button_type":{"type":"string","example":"VIEW_WEBSITE"},"website_url":{"type":"string","format":"uri"},"enable_messenger":{"type":"boolean"},"status":{"type":"string"},"lead_gen_use_case":{"type":"string"},"business_phone_number":{"type":"string"},"country_code":{"type":"string"}}},"questions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","description":"EMAIL, PHONE, FULL_NAME, CUSTOM, ..."},"inline_context":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"conditional_questions_group_id":{"type":"string","description":"READ-ONLY. Conditional logic can only be authored in Meta form builder; Meta has no create parameter for it."},"conditional_questions_choices":{"type":"array","items":{"type":"object"},"description":"READ-ONLY. Which answers reveal the conditional group."},"dependent_conditional_questions":{"type":"array","items":{"type":"object"},"description":"READ-ONLY. Questions revealed by the conditional group."}}}}}},"MetaInstagramIdentityRef":{"type":"object","required":["igUserId","username"],"properties":{"igUserId":{"type":"string","description":"Instagram identity ID."},"username":{"type":"string","description":"Instagram username; empty when Meta does not expose it."},"profilePictureUrl":{"type":"string","description":"Profile picture URL when available."}}},"GoogleBusinessReview":{"type":"object","description":"A Google Business Profile review, as returned by every gmb-reviews read endpoint.","properties":{"id":{"type":"string","description":"Review ID"},"name":{"type":"string","description":"Full resource name"},"reviewer":{"type":"object","properties":{"displayName":{"type":"string"},"profilePhotoUrl":{"type":["string","null"]},"isAnonymous":{"type":"boolean"}}},"rating":{"type":"integer","minimum":0,"maximum":5,"description":"Numeric star rating (0 when Google sends no rating)"},"starRating":{"type":"string","enum":["ONE","TWO","THREE","FOUR","FIVE"],"description":"Google's string rating"},"comment":{"type":"string","description":"Review text"},"createTime":{"type":"string","format":"date-time"},"updateTime":{"type":"string","format":"date-time"},"reviewReply":{"type":["object","null"],"properties":{"comment":{"type":"string","description":"Business owner reply"},"updateTime":{"type":"string","format":"date-time"}}},"photoCount":{"type":"integer","description":"Number of photos attached to the review (photos only, videos are not counted)"},"photos":{"type":"array","description":"Photos attached to the review by the reviewer","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"}}}}}},"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","whatsapp"]},"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"},"deliveryStatus":{"type":["string","null"],"enum":["delivered","read","failed",null],"description":"WhatsApp only. What Meta reported for the latest send, null until it reports. Returned by GET /v1/verify/verifications/{verificationId} (null on create and check responses).\n\nA code that never reached the recipient (for example a number not on WhatsApp) reads failed, with the Meta error in deliveryErrorCode. failed does not settle the verification: Meta can report failed and later deliver the same message.\n\nReported for at least an hour after the send, well past any code's expiry."},"deliveryErrorCode":{"type":["integer","null"],"description":"Meta error code when deliveryStatus is failed (e.g. 131026, message undeliverable)."},"createdAt":{"type":"string","format":"date-time"},"resend":{"type":"boolean","description":"Present on create responses: true when an active verification was resent instead of created."}}},"ImessageSenderLifecycle":{"type":"object","description":"A provisioned iMessage sender order and its lifecycle. Activation is asynchronous: poll GET /v1/imessage/senders/{senderId} or subscribe to account.connected.","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["phone","email"]},"region":{"type":["string","null"],"enum":["US","GB",null]},"handle":{"type":["string","null"],"description":"The sender handle once activation assigns it"},"optInLink":{"type":["string","null"],"description":"imessage:// deep link that opens Messages on this sender with a prefilled text. Share it so contacts message you first (Apple only lets a sender reach contacts who wrote to it first); null until the handle is assigned."},"status":{"type":"string","enum":["ordering","awaiting_payment","activating","active","suspended","canceled","failed"],"description":"`awaiting_payment`: the first-month charge is still being confirmed by the card; the number is ordered automatically once it is paid (usually under 5 minutes), or the order fails with `failureReason` when the card declines or nothing confirms within 30 minutes."},"priceCents":{"type":"integer","description":"Monthly price billed while the sender is active"},"provider":{"type":"string"},"profileId":{"type":"string"},"displayName":{"type":["string","null"]},"failureReason":{"type":["string","null"]},"accountId":{"type":["string","null"],"description":"The messaging account created at activation"},"createdAt":{"type":"string","format":"date-time"}}},"ImessageSandboxContact":{"type":"object","properties":{"id":{"type":"string"},"handle":{"type":"string","description":"Phone (E.164) or lowercase Apple ID email"},"status":{"type":"string","enum":["pending","active"]},"joinText":{"type":"string","description":"Send this from the handle to the sandbox line to activate it"},"joinLink":{"type":"string","description":"Opens Messages on the sandbox line with joinText prefilled"},"activatedAt":{"type":["string","null"],"format":"date-time"},"lastInboundAt":{"type":["string","null"],"format":"date-time","description":"Replies are allowed for 24 hours after this"},"createdAt":{"type":"string","format":"date-time"}}},"ImessageAudienceContact":{"type":"object","properties":{"conversationId":{"type":"string"},"accountId":{"type":"string"},"contact":{"type":"string","description":"The contact handle (E.164 phone or email)"},"name":{"type":["string","null"]},"subscribed":{"type":"boolean"},"lastMessage":{"type":["string","null"]},"lastMessageAt":{"type":["string","null"],"format":"date-time"},"firstSeenAt":{"type":["string","null"],"format":"date-time"},"optIn":{"type":["object","null"],"description":"Present when the thread was opened through a tracked opt-in link","properties":{"at":{"type":"string","format":"date-time"},"parameters":{"type":"object","additionalProperties":true}}}}},"ImessageSender":{"type":"object","description":"An iMessage sender registered as an account on a profile.","properties":{"id":{"type":"string","description":"Account id (use it with the inbox endpoints' accountId)"},"platform":{"type":"string","enum":["imessage"]},"sender":{"type":"string","description":"The sender handle (E.164 phone or email)"},"optInLink":{"type":["string","null"],"description":"imessage:// deep link that opens Messages on this sender with a prefilled text. Share it so contacts message you first (Apple only lets a sender reach contacts who wrote to it first)."},"displayName":{"type":"string"},"profileId":{"type":["string","null"]},"provider":{"type":"string","description":"Delivery provider backing this sender (e.g. loopmessage)"},"senderVerified":{"type":"boolean","description":"Whether the provider confirmed the sender as active at registration time"},"isActive":{"type":"boolean"}}},"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:<meta code>"},"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)."}}},"MessagingCarouselCard":{"type":"object","required":["imageUrl"],"description":"One card of a messaging ad carousel (Meta link_data.child_attachments). Every card opens the same conversation, so a card has no link of its own.","properties":{"imageUrl":{"type":"string","format":"uri","description":"Card image. Uploaded to the ad account and sent as the card image_hash (by URL on validateOnly)."},"headline":{"type":"string","maxLength":255,"description":"Card title (Meta name)."},"description":{"type":"string","maxLength":255,"description":"Card description, under the title."},"callToAction":{"type":"string","description":"Optional. Must equal the destination's messaging call to action (WHATSAPP_MESSAGE for whatsapp, MESSAGE_PAGE for messenger, INSTAGRAM_MESSAGE for instagram_direct; with `destinations` the first one listed). Any other value is a 400 naming the card, because Meta refuses a carousel whose cards do not all open the destination."},"linkUrl":{"type":"string","description":"Not accepted: a 400. The card tap opens the conversation, not a website."}}},"CtwaAdRequestBody":{"type":"object","required":["accountId","adAccountId","name"],"description":"Besides the `required` list, the request must use EXACTLY ONE of these shapes:\n\n- Single-creative: `headline`, `body`, and one of `imageUrl` / `video`, OR `platformPostId` / `objectStoryId` to reuse an organic post. On POST /v1/ads/messaging, `placementAssets` can replace `imageUrl` / `video`.\n- Carousel (messaging and CTWA): `body` and `carouselCards` (2-10 image cards) instead of `imageUrl` / `video`, top level or per `creatives[]` entry.\n- Multi-creative: a non-empty `creatives[]` array. Top-level creative fields must NOT be set on this shape.\n\n**Existing post references** work on messaging and CTWA only (not call ads). They cannot be combined with each other or with headline, body, imageUrl or video. `welcomeMessage` works on them (it lives on the ad, not the post).\n\nNo media is uploaded and the organic post is retained. Fresh creatives still require headline, body, and image or video.\n\nThe route enforces this at the Zod boundary; OpenAPI's `required` cannot express the OR cleanly.\n\n**Campaign, ad set and targeting fields** match POST /v1/ads/create on Meta and run through the same builders:\n\n- the full targeting set (including `rawTargeting`, `languages`, `gender`, exclusions and `savedTargetingId`);\n- `budgetLevel` (campaign budget);\n- `startDate` / `endDate` in the ad account timezone;\n- `existingCampaignId` to add a new ad set to a campaign you already have.\n","properties":{"retryOnServerError":{"type":"boolean","default":true,"description":"When Meta answers a create with a 5xx and reading the parent back by name finds no such object, Zernio sends the create again (at most 3 POSTs per object, never for an object created ACTIVE) and reports it in `recoveredWrites`.\n\n`false` never sends it again: the request fails with 502 and `details.unconfirmedWrite`, so you can check the parent yourself. One object found by name is still reused.\n"},"creativeFeatures":{"$ref":"#/components/schemas/MetaCreativeFeatures","description":"Meta enhancement settings for single or attached ads, and defaults for creatives[]. An item replaces the entire map, including with an empty object."},"tracking":{"$ref":"#/components/schemas/AdTracking"},"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.\nOn the multi-creative shape, each ad's Meta name gets a\n\" #N\" suffix (1-indexed) so Ads Manager shows them as a\nnumbered batch.\n"},"campaignName":{"type":"string","maxLength":255,"description":"Exact name for the campaign this request provisions. Omitted keeps `<name> - Campaign`. Ignored with `adSetId` (the ad set already has a campaign)."},"adSetName":{"type":"string","maxLength":255,"description":"Exact name for the ad set this request provisions. Omitted keeps `<name> - Ad Set`. Ignored with `adSetId`."},"platformPostId":{"type":"string","minLength":1,"description":"Messaging and CTWA only. Platform post or reel ID, the same input boostPost takes as platformPostId. Mutually exclusive with objectStoryId and fresh creative fields.\n\n- Facebook IDs become object_story_id.\n- Instagram IDs become source_instagram_media_id, run as the media owner (resolved from the media on a Meta ads business-login connection, so no Instagram connection is needed).\n"},"existingPostId":{"type":"string","minLength":1,"deprecated":true,"description":"Alias of platformPostId, kept for existing callers. Sending both with different values is a 400."},"objectStoryId":{"type":"string","pattern":"^\\d+_\\d+$","description":"Messaging and CTWA only. Raw Facebook pageId_postId reference, used as object_story_id even with an Instagram account. Mutually exclusive with platformPostId and fresh creative fields."},"pageId":{"type":"string","description":"Facebook Page the ad runs as, when the connection was granted several Pages. Defaults to the Page bound to the connection. Any Page granted to the connection is accepted; other ids answer 400 listing the granted Pages. Same semantics as `pageId` on POST /v1/ads/create."},"whatsappPhoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"WhatsApp only. Optional E.164 number already paired with the Facebook Page. Omit to let Meta select the paired number.\n\n- Sent to the creative CTA and, when creating a new ad set, its promoted_object.\n- Meta can accept the number yet create the ad set without it; the response then carries a `warnings` entry.\n- Attach requests do not change the existing ad set.\n- Stored as creative.whatsappPhoneNumber on every created ad.\n"},"headline":{"type":"string","minLength":1,"maxLength":255,"description":"Single-creative shape only. Mutually exclusive with\n`creatives[]`. Required on a single image or video ad (including\none built with `placementAssets`); not used by a `carouselCards`\nad and not accepted with an existing post reference.\n"},"body":{"type":"string","minLength":1,"description":"Primary text shown above the image / video. Single-creative\nshape only. Mutually exclusive with `creatives[]`.\n"},"description":{"type":"string","minLength":1,"maxLength":255,"description":"Link description, independent of `headline` and `body`: Meta's `link_data.description`, `video_data.link_description` on video, and the shared description of a `placementAssets` feed.\n\nMeta shows it mainly on Facebook Feed placements, under the headline, when there is room. Instagram, Stories, Reels and Messenger placements do not display it.\n\nAlso accepted per entry in `creatives[]`. Not allowed with an existing post creative.\n"},"imageUrl":{"type":"string","format":"uri","description":"Image asset for single-creative shape. Mutually exclusive\nwith `video` and with `creatives[]`. Required on the\nsingle-creative shape if neither `video` nor an existing post reference is supplied.\n"},"video":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Public URL of the video to upload. Provide either `url` or `id`."},"id":{"type":"string","description":"Reuse a video already uploaded to this ad account (list them with GET /v1/ads/videos) instead of re-uploading. Wins over `url`. Provide either `url` or `id`. Meta: a video still processing is waited on for up to 30 s, then answered 409 `invalid_resource_state` (poll GET /v1/ads/videos/{videoId})."},"thumbnailUrl":{"type":"string","format":"uri","description":"OPTIONAL: when omitted, the poster is auto-generated from\nMeta's own preferred video thumbnail. When Meta produces no\ncandidate the request fails with a 502 platform_error\n(reason: video_thumbnail_unavailable). Retry, or supply\nthis field to control the poster frame exactly.\n"}},"description":"Video creative for single-creative shape. Mutually\nexclusive with `imageUrl` and with `creatives[]`. Required\non the single-creative shape if neither `imageUrl` nor an existing post reference is supplied.\n"},"welcomeMessage":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"description":"Greeting shown when the chat opens. Replaces Meta's default (\"Hi! Can we help you?\")."},"prefillText":{"type":"string","minLength":1,"description":"Message put into the user's text input, ready to send. Replaces Meta's default (\"Hi! I want more info.\"). Lets one ad steer the opening message toward what it promotes (e.g. a specific product). Exactly one of prefillText or quickReplies."},"quickReplies":{"type":"array","minItems":1,"maxItems":13,"items":{"type":"object","required":["title","payload"],"properties":{"title":{"type":"string","minLength":1,"maxLength":20,"description":"Chip label the person taps."},"payload":{"type":"string","minLength":1,"maxLength":1000,"description":"Opaque string you choose; delivered on the message.received webhook as interactiveMetadata.quickReplyPayload when the chip is tapped."}}},"description":"Tappable chips under the greeting instead of a prefilled message. Exactly one of prefillText or quickReplies.\n\nPut your own campaign or ad key in each payload. The tap arrives on the messages webhook with that payload even where Meta delivers no ad referral (Pages owned by an EU business under the Europe/Japan Messenger restrictions).\n"}},"description":"Custom chat welcome message (Meta's `page_welcome_message`,\n\"Mensaje de bienvenida\" / \"Mensaje predefinido\" in Ads Manager).\nSingle-creative shape only; for `creatives[]` set it per entry.\n"},"carouselCards":{"type":"array","minItems":2,"maxItems":10,"items":{"$ref":"#/components/schemas/MessagingCarouselCard"},"description":"Messaging and CTWA only (a 400 on POST /v1/ads/call). A hand-built carousel of 2-10 image cards, sent to Meta in the given order as `link_data.child_attachments`.\n\n- Meta may reorder cards for performance, since `multi_share_optimized` defaults to true; `optimizeCardOrder: false` keeps your order.\n- Every card (and the carousel) carries the destination's messaging call to action (WHATSAPP_MESSAGE, MESSAGE_PAGE or INSTAGRAM_MESSAGE), so a tap on any card opens the conversation.\n- Replaces `imageUrl` / `video` (sending either is a 400).\n- `body` is required as the primary text. `headline` is optional and only names the creative (each card has its own `headline`). A top-level `description` is a 400 (set it per card).\n- `welcomeMessage`, `whatsappPhoneNumber` and `destinations` apply as on a single-image ad.\n- Also a 400 with `placementAssets`, `platformPostId`, `existingPostId` or `objectStoryId`.\n- Single-creative shape; for `creatives[]` set it per entry.\n"},"optimizeCardOrder":{"type":"boolean","description":"Only with `carouselCards` (a 400 without them). Single-creative shape; for `creatives[]` set it per entry. Sets the creative's `link_data.multi_share_optimized`.\n\n- `false`: keeps the cards in the order given. Meta then takes at most 5 cards, so `false` with more than 5 `carouselCards` is a 400.\n- `true`: lets Meta pick and reorder the cards for performance (up to 10).\n- Omitted: nothing is sent and Meta's default (`true`) applies.\n"},"creatives":{"type":"array","minItems":1,"description":"Multi-creative shape: N CTWA ads under one campaign + one ad set, sharing budget and targeting. Fresh and existing creatives can be mixed.\n\nEach entry supplies headline, body, and image/video, or a platformPostId or objectStoryId reference.\n\nMutually exclusive with the top-level single-creative fields (`headline` / `body` / `imageUrl` / `video`): setting both is a 400. This differs from `POST /v1/ads/create`, where the top-level fields are silently ignored in multi-creative mode.\n","items":{"type":"object","description":"Supply headline, body, and image/video; or body and carouselCards (no headline); or exactly one existing post reference. References cannot be combined with headline, body, imageUrl, video or carouselCards; welcomeMessage works on all three.","properties":{"platformPostId":{"type":"string","minLength":1,"description":"Messaging and CTWA only. Platform post or reel ID, the same input boostPost takes as platformPostId. Mutually exclusive with objectStoryId and fresh creative fields.\n\n- Facebook IDs become object_story_id.\n- Instagram IDs become source_instagram_media_id, run as the media owner (resolved from the media on a Meta ads business-login connection, so no Instagram connection is needed).\n"},"existingPostId":{"type":"string","minLength":1,"deprecated":true,"description":"Alias of platformPostId, kept for existing callers. Sending both with different values is a 400."},"objectStoryId":{"type":"string","pattern":"^\\d+_\\d+$","description":"Messaging and CTWA only. Raw Facebook pageId_postId reference, used as object_story_id even with an Instagram account. Mutually exclusive with platformPostId and fresh creative fields."},"creativeFeatures":{"$ref":"#/components/schemas/MetaCreativeFeatures","description":"Replaces the top-level creativeFeatures map for this item. Omit to inherit; an empty object clears inherited enrollment choices."},"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\n`video`. Required if neither `video` nor an existing post reference is supplied.\n"},"video":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Public URL of the video to upload. Provide either `url` or `id`."},"id":{"type":"string","description":"Reuse a video already uploaded to this ad account (list them with GET /v1/ads/videos) instead of re-uploading. Wins over `url`. Provide either `url` or `id`. Meta: a video still processing is waited on for up to 30 s, then answered 409 `invalid_resource_state` (poll GET /v1/ads/videos/{videoId})."},"thumbnailUrl":{"type":"string","format":"uri","description":"OPTIONAL: when omitted, the poster is auto-generated\nfrom Meta's own preferred video thumbnail. When Meta\nproduces no candidate the request fails with a 502\nplatform_error (reason: video_thumbnail_unavailable).\n"}},"description":"Video creative. Mutually exclusive with this entry's\n`imageUrl`. Required if neither `imageUrl` nor an existing post reference is supplied.\n"},"welcomeMessage":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"description":"Greeting shown when the chat opens. Replaces Meta's default."},"prefillText":{"type":"string","minLength":1,"description":"Message put into the user's text input, ready to send. Replaces Meta's default. Exactly one of prefillText or quickReplies."},"quickReplies":{"type":"array","minItems":1,"maxItems":13,"items":{"type":"object","required":["title","payload"],"properties":{"title":{"type":"string","minLength":1,"maxLength":20,"description":"Chip label the person taps."},"payload":{"type":"string","minLength":1,"maxLength":1000,"description":"Opaque string you choose; delivered on the message.received webhook as interactiveMetadata.quickReplyPayload when the chip is tapped."}}},"description":"Tappable chips under the greeting instead of a prefilled message. Exactly one of prefillText or quickReplies."}},"description":"Custom chat welcome message for this entry: `text` plus exactly one of `prefillText` or `quickReplies` (400 otherwise). Same shape as the top-level `welcomeMessage` of the single-creative shape."},"carouselCards":{"type":"array","minItems":2,"maxItems":10,"items":{"$ref":"#/components/schemas/MessagingCarouselCard"},"description":"A 2-10 card carousel for this entry instead of `imageUrl` / `video`; `body` is required. Same rules as the top-level `carouselCards`. Carousel and single-media entries can be mixed on one ad set."}}}},"adSetId":{"type":"string","description":"Attaches the creatives to this EXISTING messaging ad set instead of building a campaign, so the ad set keeps its learning phase. Its `destination_type` must match the ad's destination.\n\nThe ad set then owns budget, targeting and schedule, so these are rejected with a 400 alongside it: `budgetAmount`, `budgetType`, `budgetLevel`, `startDate`, `endDate`, `objective`, `campaignStatus`, `adSetStatus`, `existingCampaignId`, the special ad category fields, and every targeting field except `ageMin`, `ageMax`, `placements` and `advantageAudience`.\n"},"existingCampaignId":{"type":"string","pattern":"^\\d+$","description":"Creates the new messaging ad set (and its ads) under this EXISTING Meta campaign instead of a new one, e.g. several audience ad sets under one campaign. To add ads to an existing ad set instead, use `adSetId`.\n\n- The campaign's objective must be OUTCOME_ENGAGEMENT, OUTCOME_SALES or OUTCOME_LEADS (400 otherwise).\n- If the campaign has a campaign budget, omit `budgetAmount` and `budgetType` (400 if sent). Otherwise they are required and land on the new ad set.\n- `objective`, `campaignName`, `campaignStatus`, `budgetLevel`, `specialAdCategories`, `specialAdCategoryCountry` and `adSetId` are rejected alongside it.\n"},"budgetLevel":{"type":"string","enum":["adset","campaign"],"description":"Where the budget lives. `adset` (default) puts it on the new ad\nset. `campaign` creates an Advantage campaign budget (CBO): the\nbudget and bid strategy sit on the campaign and the ad set\ninherits them, same as POST /v1/ads/create. Not allowed with\n`adSetId` or `existingCampaignId`.\n"},"budgetAmount":{"type":"number","exclusiveMinimum":0,"description":"Budget amount in the ad account's currency major units\n(e.g. dollars for USD, not cents). Must be > 0.\nRequired unless `adSetId` is set (the ad set owns it) or\n`existingCampaignId` names a campaign with a campaign budget.\n"},"budgetType":{"type":"string","enum":["daily","lifetime"],"description":"Required unless `adSetId` is set or `existingCampaignId` names a campaign with a campaign budget. `lifetime` requires `endDate`."},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code matching the ad account's currency\n(e.g. `USD`). Optional: Zernio resolves it from the ad account\nwhen omitted. The value selects the minor-unit exponent Zernio\nconverts budget/bid amounts by before calling Meta (most\ncurrencies are cents; zero-decimal currencies like JPY/KRW are\nsent as-is).\n"},"startDate":{"type":"string","description":"When the ad set starts delivering. ISO 8601 date or date-time. A\nvalue with an offset (`2027-01-15T10:00:00+01:00`, `...Z`) is used\nas is; one without an offset (`2027-01-15T10:00:00`) is read in the\nad account's timezone, and a date-only value starts at 00:00 local.\nDefaults to now.\n"},"endDate":{"type":"string","description":"ISO 8601 date or date-time, read like `startDate`; a date-only\nvalue ends at 23:59:59 local. Required when `budgetType` is\n`lifetime`.\n"},"countries":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"description":"ISO 3166-1 alpha-2 country codes. Defaults to `[\"US\"]` only\nwhen no other geo (`cities`, `regions`, `zips`, `metros`,\n`customLocations`) is supplied.\n"},"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.\n\n`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).\n","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\nID (lookupable via GET /v1/ads/targeting/search?type=region).\n","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\npostal id resolved via /v1/ads/targeting/search.\n","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\n(e.g. `DMA:807`).\n","items":{"type":"object","required":["key"],"properties":{"key":{"type":"string","minLength":1},"name":{"type":"string"}}}},"countryGroups":{"type":"array","description":"Meta only. Continents and trade blocs (`geo_locations.country_groups`),\nfor targeting a whole region without listing its countries. Combines\nwith `countries` rather than replacing it, and is also accepted under\n`excludedLocations`. Discoverable via\n`GET /v1/ads/targeting/search?dimension=geo&geoType=country_group`.\n","items":{"type":"string","enum":["africa","asia","europe","north_america","south_america","oceania","central_america","caribbean","eea","euro_area","nafta","mercosur","afta","apec","gcc","cisfta","emerging_markets","itunes_app_store","android_free_store","android_paid_store"]}},"customLocations":{"type":"array","description":"Point-radius geo (Meta `geo_locations.custom_locations`).\nUse for targeting a radius around a specific lat/long when\nno Meta city/region key fits. `distanceUnit` is required.\n","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.\n\nWhen 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}`.\n\nEnum 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.\n","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","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."}}},"gender":{"type":"string","enum":["all","male","female"],"description":"Restrict the audience by gender (Meta `genders`). Omit or send all for everyone; all is ignored in adSetId attach mode. Stored on the ad and read back in `targeting.gender`."},"languages":{"type":"array","items":{"type":"string"},"description":"Audience languages (Meta `locales`). A bare ISO 639-1 code targets all regional variants (\"en\" = all English), a region-qualified code a specific one (\"en_GB\", \"pt_BR\"). Meta numeric locale ids (e.g. \"24\" for English UK) are also accepted. Unknown values are rejected. Same format as `targeting.languages` on POST /v1/ads/boost."},"places":{"type":"array","items":{"type":"object","required":["key"],"properties":{"key":{"type":"string"}}},"description":"Meta place keys (from GET /v1/ads/targeting/search)."},"neighborhoods":{"type":"array","items":{"type":"object","required":["key"],"properties":{"key":{"type":"string"}}},"description":"Meta neighborhood keys (from GET /v1/ads/targeting/search)."},"excludedLocations":{"type":"object","description":"Geo to exclude, same shape as POST /v1/ads/create (countries, countryGroups, regions, cities, zips, places, neighborhoods, customLocations).","additionalProperties":true},"behaviors":{"type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"description":"Behavior ids from /v1/ads/targeting/search?dimension=behavior. Meta: each dimension is its own flexible_spec entry (OR within, AND across). TikTok: video/creator interaction categories, sent as the ad group's actions."},"workPositions":{"type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"workEmployers":{"type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"workIndustries":{"type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"incomeTier":{"type":"string","enum":["top_5","top_10","top_10_25","top_25_50"],"description":"Normalized household-income tier, same as POST /v1/ads/create. Incompatible with housing, employment and credit specialAdCategories."},"userOs":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Meta `user_os`, e.g. [\"iOS_ver_14.0_and_above\"]."},"userDevice":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Meta `user_device`."},"audienceInclude":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Custom or lookalike audience ids to include."},"audienceExclude":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Custom or lookalike audience ids to exclude."},"savedTargetingId":{"type":"string","description":"ID of a saved_targeting audience (POST /v1/ads/audiences), expanded as the base targeting. Precedence: savedTargetingId, then `targeting`, then the flat fields."},"targeting":{"$ref":"#/components/schemas/TargetingSpec","description":"Nested targeting object, same contract as POST /v1/ads/create and boost. Flat fields win per key."},"rawTargeting":{"type":"object","additionalProperties":true,"description":"Meta targeting spec sent as the BASE layer of the ad set's `targeting`, exactly as POST /v1/ads/create does. Use it for anything the flat fields cannot express, such as a layered `flexible_spec` (entries AND together, ids inside one entry OR).\n\nFlat fields you also send are layered on top and win per key.\n\nWith rawTargeting present the US geo and `advantage_audience: 0` defaults are not injected, so include `targeting_automation` in it (or send `advantageAudience`), as Meta requires it on create.\n"},"specialAdCategories":{"type":"array","items":{"type":"string","enum":["HOUSING","EMPLOYMENT","CREDIT","ISSUES_ELECTIONS_POLITICS","FINANCIAL_PRODUCTS_SERVICES","ONLINE_GAMBLING_AND_GAMING"]},"description":"Meta special ad categories on the new campaign."},"specialAdCategoryCountry":{"type":"array","items":{"type":"string"},"description":"Countries the special ad category applies to. Requires specialAdCategories."},"advantageAudience":{"type":"integer","enum":[0,1],"description":"Meta's Advantage+ audience expansion. `0` (default) keeps\ntargeting strict; `1` lets Meta expand beyond the supplied\ntargeting when its delivery system finds better matches.\nAlways sent on CREATE (Meta requires it).\n"},"objective":{"type":"string","enum":["OUTCOME_ENGAGEMENT","OUTCOME_SALES","OUTCOME_LEADS"],"description":"Defaults to `OUTCOME_ENGAGEMENT`. `OUTCOME_SALES` and `OUTCOME_LEADS` require\nadditional account configuration (Dataset linked to the WABA\nfor sales) and may be rejected by Meta if missing.\n"},"status":{"type":"string","enum":["ACTIVE","PAUSED"],"description":"Defaults to `ACTIVE`. `PAUSED` pauses only the top-most object this\ncall creates: the new campaign (ad set and ads switched on), or, with\n`adSetId`, the new ads themselves.\n"},"campaignStatus":{"type":"string","enum":["ACTIVE","PAUSED"],"description":"Campaign-level status, same semantics as `POST /v1/ads/create`. Defaults to `status`.\n\n- `PAUSED`: holds the new campaign off while the ad set and ads switch on (one resume call brings the whole hierarchy live).\n- `ACTIVE` with `status: PAUSED`: switches the campaign on and pauses the new ad set instead.\n\nOnly meaningful when a new campaign is created. Rejected with a 400 alongside `adSetId` (the attach shape reuses an existing campaign).\n"},"adSetStatus":{"type":"string","enum":["ACTIVE","PAUSED"],"description":"Ad-set-level status, same semantics as `POST /v1/ads/create`. Sets the new ad set's switch alone and overrides `status` for it.\n\nA level status (`campaignStatus`, `adSetStatus`, `adStatus`) always wins for its level, and `status: PAUSED` adds a hold of its own only when none of them is PAUSED.\n\nRejected with a 400 alongside `adSetId` (that ad set already exists).\n"},"adStatus":{"$ref":"#/components/schemas/AdActivationStatus","description":"Ad-level status, same semantics as `POST /v1/ads/create`. Sets the\nnew ads' switch and overrides `status` for them, also with\n`adSetId`. Send `campaignStatus`, `adSetStatus` and `adStatus` all\nPAUSED to create every object paused.\n"},"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\n`LOWEST_COST_WITHOUT_CAP` (auto-bid) when omitted.\n`LOWEST_COST_WITH_BID_CAP` and `COST_CAP` require\n`bidAmount`. `LOWEST_COST_WITH_MIN_ROAS` requires\n`roasAverageFloor`. CTWA's `optimization_goal` is fixed to\n`CONVERSATIONS`, but the bid strategy is independent.\n"},"bidAmount":{"type":"number","exclusiveMinimum":0,"description":"Whole currency units (e.g. `5` = $5.00 on a USD account).\nRequired when `bidStrategy` is `LOWEST_COST_WITH_BID_CAP`\nor `COST_CAP`; rejected otherwise.\n"},"roasAverageFloor":{"type":"number","exclusiveMinimum":0,"description":"Decimal ROAS multiplier (e.g. `2.0` = 2.0× ROAS floor).\nRequired when `bidStrategy` is `LOWEST_COST_WITH_MIN_ROAS`;\nrejected otherwise. Meta enforces its own upper bound\nserver-side.\n"},"dsaBeneficiary":{"type":"string","maxLength":100,"description":"Legal entity that benefits from the ad. Required when targeting EU users\n(EU DSA, Article 26). Optional if the ad account has a default beneficiary:\nset it once via `PATCH /v1/ads/accounts` or in Meta Ads Manager, and Meta\nfills it in whenever the field is omitted.\n"},"dsaPayor":{"type":"string","maxLength":100,"description":"Legal entity that pays for the ad. Can differ from `dsaBeneficiary`\n(for example, an agency paying for a client's ads). Same rules as\n`dsaBeneficiary`: required for EU targeting unless the ad account has\na default payor.\n"},"regionalRegulatedCategories":{"type":"array","description":"Meta only. Regional regulation categories required when the ad set targets certain countries (e.g. AUSTRALIA_FINSERV, AUSTRALIA_UNIVERSAL, BRAZIL_REGULATION, INDIA_FINSERV, MALAYSIA_UNIVERSAL, SINGAPORE_UNIVERSAL, TAIWAN_FINSERV, TAIWAN_UNIVERSAL, THAILAND_UNIVERSAL). Forwarded to the ad set.","items":{"type":"string"}},"regionalRegulationIdentities":{"type":"object","additionalProperties":{"type":["string","integer"]},"description":"Meta only. Verified identity IDs of the beneficiary and payer for each declared regionalRegulatedCategories value. Ignored when adSetId adds the ad to an existing ad set.\n\nMeta may require them on API-created ad sets even when a default beneficiary and payer are set in Ads Manager (seen on AUSTRALIA_FINSERV), so sending them explicitly is the reliable path.\n\n**Value:** the Verified identity ID (Meta Business Settings > Verified identities), not a Page or Business ID. Beneficiary and payer may be the same ID. The IDs reach Meta unchanged.\n\nSend each ID as a string of digits: IDs can have 17 digits, more than a JSON number holds exactly, and a rounded number is rejected. Numbers up to 9007199254740991 are still accepted.\n\n**Keys by category:**\n\n- AUSTRALIA_FINSERV: australia_finserv_beneficiary / australia_finserv_payer\n- TAIWAN_FINSERV: taiwan_finserv_beneficiary / taiwan_finserv_payer\n- INDIA_FINSERV: india_finserv_beneficiary / india_finserv_payer\n- TAIWAN_UNIVERSAL: taiwan_universal_beneficiary / taiwan_universal_payer\n- SINGAPORE_UNIVERSAL: singapore_universal_beneficiary / singapore_universal_payer\n- AUSTRALIA_UNIVERSAL, BRAZIL_REGULATION, MALAYSIA_UNIVERSAL and THAILAND_UNIVERSAL: universal_beneficiary / universal_payer\n\nWhen Meta rejects the ad set for a missing verified advertiser, the error carries param regionalRegulationIdentities, details.expectedIdentityKeys (keys the declared categories expect), details.suggestedCategories (markets Meta ties to that subcode) and Meta's metaCode, metaSubcode and fbtraceId.\n"}}},"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 17 supported types break into four groups:\n  messaging (send_message),\n  control flow (trigger, condition, delay, wait_for_reply, a_b_split, end),\n  data ops (set_variable, set_field, add_tag, remove_tag, enroll_sequence),\n  integrations (webhook, hubspot_upsert_contact, ai, handoff, start_call).\n","enum":["trigger","send_message","wait_for_reply","condition","set_variable","delay","webhook","hubspot_upsert_contact","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. Every string field supports `{{variable}}` interpolation against the run's variable bag, resolved at execution time.\n\n**trigger**: `{ triggerType: inbound_message|api_call|whatsapp_event|referral|story_mention|comment|reaction|lead_received, keywords:[string], matchType: any|contains|exact|regex, onlyFirstMessage:boolean, eventType: message_sent|message_delivered|message_read|message_failed|reaction, referral:{ ref, matchType: exact|prefix|any }, reaction:{ emojis:[string] }, comment:{ keywords:[string], matchType: any|contains|exact|regex, platformPostId }, leadReceived:{ formIds:[string], pageAccountIds:[string], consentCheckboxKey, defaultCountry, allowCrossProfile:boolean }, cooldownHours:int (1-720) }`.\n\nDefault `triggerType` is `inbound_message` for legacy nodes. A workflow starts only on events of its own trigger type:\n\n- `inbound_message`: a message.\n- `referral`: an ig.me / m.me / click-to-message ad referral (standalone, or the first message carrying one). The two are deduplicated per conversation within 60 seconds.\n- `story_mention`: an Instagram story mention.\n- `reaction`: a reaction (Instagram, Facebook, WhatsApp, Telegram groups).\n- `comment`: an Instagram or Facebook comment (see below).\n- `whatsapp_event`: a WhatsApp status of a message we sent, filtered by `eventType`.\n- `api_call`: only via `POST /v1/workflows/{workflowId}/trigger`.\n- `lead_received` (WhatsApp workflows only): a Meta lead ad form is submitted.\n\n**`comment` runs** start with no conversation. The first `send_message` is sent as a private reply to the comment, and the run continues in the conversation that reply opens.\n\nThat first `send_message` must follow the trigger directly and be text (optionally with buttons or quick replies) or cards (checked on save). On some Instagram accounts Meta refuses buttons and cards to commenters who do not follow the account.\n\nWhen an active comment automation's keywords match the comment, the automation answers and the workflow does not start.\n\n**`lead_received`** needs `leadReceived.consentCheckboxKey` and at least one of `formIds` or `pageAccountIds`. A form scope wins over a Page scope, then the earliest activated workflow. It starts only for leads that:\n\n- were submitted in the last hour and after the workflow was activated;\n- have the consent checkbox ticked (the form's custom disclaimer, see `POST /v1/ads/lead-forms`);\n- have a phone number that parses to a valid international number (`defaultCountry`, ISO 3166 alpha-2, defaults to the country of the workflow's WhatsApp number).\n\nOtherwise the lead is marked `unreachable`. The Page and the WhatsApp number must be in the same profile unless `allowCrossProfile` is true. Every send or call reached first from the trigger must be a WhatsApp template (checked on save).\n\n**Other trigger rules**:\n\n- `referral.matchType` defaults to `any`.\n- `cooldownHours` stops the same contact from starting the workflow again inside the window. It applies to inbound_message, referral, story_mention, reaction, whatsapp_event and lead_received, where it defaults to 24.\n- A `whatsapp_event` workflow never starts on the status of a message a workflow, sequence or comment automation sent.\n- A redelivered platform event never starts the same workflow twice.\n\n**Variables** available from the start of every run (absent values are `''`):\n\n- Message: `lastMessage`, `inboundText`, `triggerText`, `conversationId`.\n- Contact: `contact.name`, `contact.phone`, `contact.handle`, `contact.tags` (array), `contact.fields` (the contact's custom fields object), `contact.lastInteractionAt` (ISO date), `contact.lastInteractionHoursAgo` (number), `contact.isFollower` (Instagram, from the stored profile: true, false or `''` when unknown).\n- Referral: `referral.ref`, `referral.source`, `referral.type`, `referral.adId`, `referral.adTitle` (the ad title or headline Meta sent), `referral.adName` (the synced ad's name, else `referral.adTitle`), `referral.campaignName` (the synced ad's campaign).\n- Taps: `postback.payload`, `postback.title`, `quickReply.payload`, `quickReply.title`.\n- Story and comment: `story.id`, `story.url`, `comment.id`, `comment.text`, `comment.platformPostId`.\n- Reaction: `reaction.emoji`, `reaction.action` (added|removed).\n\n`api_call` runs also get the request's `variables`, merged over these. `lead_received` runs also get `lead.id`, `lead.leadgenId`, `lead.formId`, `lead.formName`, `lead.adId`, `lead.adsetId`, `lead.campaignId` and every form answer by its key (`lead.full_name`, `lead.email`, `lead.phone_number`).\n\nTemplate `variableMapping` entries with `field: custom` interpolate `{{...}}` in `customValue`. An array or object interpolated into text renders as JSON.\n\n**send_message**: `{ messageType: text|template|media|interactive|cards, text, template, media:{mediaType:image|video|audio|document, url,caption}, interactive, buttons, quickReplies, messageTag }`.\n\n- `template` is `{name,language,variableMapping}` for `messageType: template`, and `{ type: generic, elements:[{ title, subtitle, imageUrl, buttons }] }` (1 to 10 cards) for `messageType: cards`.\n- `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.\n- Facebook and Instagram only (a 400 on other platforms; WhatsApp keeps `interactive`): `cards`, `buttons` on `text` (cards carry their own buttons), and `quickReplies` / `messageTag` on `text`, `media` and `cards`.\n- `media` takes no `buttons` (a 400 at save).\n- `buttons:[{ type: url|postback|phone, title, url, payload, phone, workflowId }]`: 1 to 3, text only (the text then 640 characters at most), sent as Meta's button_template, not inside cards. `phone` is Facebook-only.\n- `quickReplies:[{ title, payload, imageUrl, workflowId }]`: 1 to 13, not combined with `buttons`.\n- `messageTag` is not available: a workflow only sends within the 24h window, and `HUMAN_AGENT` is rejected with a 400 because it is only for replies typed by a person.\n- Titles are capped at 20 characters (80 for card titles and subtitles).\n- A postback button or quick reply with no `payload` gets `zernio:workflow:<this workflow id>`, so a tap answers this workflow's pending `wait_for_reply` or restarts it. With `workflowId` (a 24-hex workflow id, not combined with `payload`) the tap starts that workflow instead.\n\n**wait_for_reply**: `{ timeoutMinutes:int (max 43200), saveAs:string }`. Resumes via the `'reply'` edge on inbound, or the `'timeout'` edge after `timeoutMinutes` of silence. On Facebook and Instagram a button tap sets `{{postback.payload}}` / `{{postback.title}}` and a quick reply tap sets `{{quickReply.payload}}` / `{{quickReply.title}}`. Each reply clears the previous tap.\n\n**condition**: `{ rules:[{ id, variable, operator: equals|not_equals|contains|not_contains|starts_with|ends_with|exists|not_exists|matches|greater_than|less_than|greater_or_equal|less_or_equal|before|after|has_tag|not_has_tag|is_true|is_false, value }] }`. The first matching rule takes its `id` as the sourceHandle; otherwise `'default'`.\n\n- Text operators compare case-insensitively.\n- `greater_than`, `less_than`, `greater_or_equal` and `less_or_equal` compare numbers (a non-numeric side is false).\n- `before` and `after` compare ISO dates.\n- `has_tag` and `not_has_tag` test whether an array variable (such as `contact.tags`) contains `value`.\n- `is_true` and `is_false` take no value.\n\n**set_variable**: `{ assignments:[{ name, value }] }`. Run-scoped: lives only for this execution (use `set_field` for persistent values).\n\n**delay**: `{ delayMinutes:int (max 43200) }`. Suspends the run, resumes via timer.\n\n**webhook**: `{ url, method: GET|POST|PUT|PATCH|DELETE, headers, bodyTemplate, saveAs }`. SSRF-guarded (private/loopback/metadata IPs rejected). The response is saved as `{ status, ok, body }` to `vars[saveAs]`. Edges: `'success'` on 2xx, `'error'` otherwise.\n\n**hubspot_upsert_contact**: `{ email, phone, firstName, lastName, properties, saveAs }`. Creates or updates the run contact in the profile's connected HubSpot portal.\n\n- Updates the contact already linked by inbox sync, else one matching by email, then phone; otherwise creates one.\n- An existing contact gets only the fields the node sets (a value that resolves to an empty string is skipped). A new one also takes the Zernio contact's name, email and phone for anything left out.\n- `properties` maps HubSpot internal property names to values (at most 50).\n- Saves `{ id, created }` (or `{ error }`) to `vars[saveAs]` (default `hubspotContact`).\n- Edges: `'success'` | `'error'` (HubSpot not connected, or HubSpot refused the write).\n\n**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:<name>'` (model picked a tool), `'error'`.\n\n**handoff**: `{ note, assignTo }`. Terminates the run as `exited` and flags the conversation for a human operator.\n\n**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'`.\n\n**a_b_split**: `{ percentage: number 0-100 (default 50) }`. Random branch picker. Edges: `'a'` (with probability `percentage/100`), `'b'`.\n\n**set_field**: `{ field, value }`. Persistent custom field on the Contact (unlike `set_variable`, which is run-scoped). The field name is sanitized to `[A-Za-z0-9_]`. No-op on `api_call` runs (no contact).\n\n**enroll_sequence**: `{ sequenceId, saveAs }`. Enrolls the run's contact into a Sequence. Edges: `'success'`, `'error'`.\n\n**add_tag** / **remove_tag**: `{ tag }`. Push or pull a tag on the Contact. No-op on `api_call` runs.\n\n**end**: no config. Terminates the run as `completed`.\n"},"position":{"type":"object","description":"Canvas coordinates (ignored by the executor; used by the visual builder).","properties":{"x":{"type":"number"},"y":{"type":"number"}}},"label":{"type":"string","minLength":1,"maxLength":80,"description":"Optional display name shown on the builder canvas and inspector, falling back to the node type when absent. The nodes array is replaced wholesale on update, so it must be resent to be kept."}}},"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:\n\n- **condition**: a rule's `id`, or `'default'` (no rule matched)\n- **wait_for_reply**: `'reply'` (contact replied) | `'timeout'` (no reply in window)\n- **webhook**: `'success'` (2xx) | `'error'` (non-2xx / fetch failed)\n- **hubspot_upsert_contact**: `'success'` | `'error'` (not connected / HubSpot refused)\n- **ai**: `'success'` (text/JSON response) | `'tool:<toolName>'` (model invoked that tool) | `'error'` (upstream failure / non-JSON in JSON mode)\n- **start_call**: `'success'` | `'permission_required'` | `'failed'`\n- **a_b_split**: `'a'` | `'b'`\n- **enroll_sequence**: `'success'` | `'error'`\n"}}},"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.\n","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:\n  `send_message` → `{ messageType, text, recipient }`,\n  `webhook` → `{ url, method, statusCode, responseTimeMs, responsePreview }`,\n  `ai` → `{ model, provider, inputTokens, outputTokens, responsePreview }`,\n  `condition` → `{ matchedHandle, rulesEvaluated }`,\n  `a_b_split` → `{ percentage, chosen }`.\n"},"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\nsucceeded or all failed) and `207` (mixed). Per-row outcomes live in `results`;\nthe row's success is `ok`, and failures carry machine-readable codes in `errors`.\n","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.\nExamples: `unknown_profile:<id>`, `no_account_for_platform:<platform>`,\n`schedule_time_missing`, `rate_limited:<platform>:@<username>:<remaining>`.\n","items":{"type":"string"}}}}},"warnings":{"type":"array","description":"Top-level advisory warnings, e.g. `rows_exceed_advisory_limit:500`, `unknown_columns:<a,b,c>` (comma-separated unrecognized CSV column names), or `not_added_to_caption:<columns>` (the `hashtags` and/or `mentions` column is filled: stored on the post, not added to the caption). Empty when none.","items":{"type":"string"}},"rateLimitedAccounts":{"type":"array","description":"Present only when one or more rows targeted an account currently in cooldown.\nLets callers map `rate_limited:*` row errors back to structured metadata without\nparsing the error strings.\n","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"}}}},"RedditComment":{"type":"object","description":"One comment of a Reddit thread as returned by GET /v1/reddit/comments/{postId}; the list is flat and in thread order","properties":{"id":{"type":"string","description":"Reddit comment ID (without type prefix)"},"fullname":{"type":"string","description":"Reddit fullname (e.g. t1_abc123)"},"parentId":{"type":"string","description":"Fullname of what the comment answers: the post (t3_…) or a parent comment (t1_…)"},"author":{"type":"string","description":"The username, or [deleted]"},"body":{"type":"string","description":"Comment text as written (Markdown, not HTML-escaped), or [deleted] / [removed]"},"permalink":{"type":"string","description":"Full permalink to the comment"},"createdUtc":{"type":"number","description":"Unix timestamp of the comment"},"score":{"type":"integer"},"numReplies":{"type":"integer","description":"Direct replies included in this response; replies Reddit left out are listed in more"},"depth":{"type":"integer","description":"0 for a top-level comment of this response, 1 for a reply to it, and so on"},"isSubmitter":{"type":"boolean","description":"Whether the author is the post's author"},"edited":{"type":"boolean"},"stickied":{"type":"boolean"},"distinguished":{"type":["string","null"],"description":"\"moderator\" or \"admin\" when the comment is distinguished, else null"}}},"ExternalPostSummary":{"type":"object","description":"A post synced from a platform (published directly on the platform, not\nthrough Zernio). Returned by GET /v1/posts?source=external and\nPOST /v1/posts/sync-external. Analytics are exposed separately via\nGET /v1/analytics?source=external.\n","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)"},"thumbnailUrl":{"type":"string","description":"Thumbnail URL"},"mediaItems":{"type":"array","description":"Per-item media (for carousels / multi-media posts)","items":{"type":"object"}},"mediaProductType":{"type":"string","description":"Instagram only: the platform media product type (e.g. FEED, REELS, STORY, AD). Absent when the platform did not report it."},"isAiGenerated":{"type":"boolean","description":"Instagram only: whether Instagram labeled the media as AI-generated. Absent when the platform did not report it."},"isSharedToFeed":{"type":"boolean","description":"Instagram reels only: whether the reel is also shared to the main feed. Absent when the platform did not report it."},"mediaAudioType":{"type":"string","description":"Instagram only: audio type of the media (MUSIC or ORIGINAL_SOUND). Absent when the platform did not report it."},"analytics":{"type":"object","description":"Engagement + insights for the post. `likes` and `comments` are\navailable immediately after an on-demand sync (they come from the\nplatform listing). `reach`, `impressions`, `views` depend on the\nplatform's insights, which carry their own delay (e.g. ~24h on\nInstagram) and read 0 until the platform makes them available.\n","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","description":"Percentage, rounded to 2 decimals. Same definition as PostAnalytics.engagementRate: (likes + comments + shares + saves) / (impressions or reach or views) * 100, where the denominator is the first of the three that is non-zero. Clicks and follows are never counted."},"lastUpdated":{"type":"string","format":"date-time","description":"When these metrics were last refreshed"}}}}},"MetaPageOwnership":{"type":"object","properties":{"id":{"type":"string","description":"Facebook Page id."},"name":{"type":"string"},"business":{"type":["object","null"],"description":"Business portfolio that owns the Page; null when the Page is outside any portfolio.","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"instagramBusinessAccount":{"type":["object","null"],"description":"Instagram professional account linked to the Page; null when none is linked.","properties":{"id":{"type":"string"},"username":{"type":"string"}}}}},"MetaPagePartner":{"type":"object","properties":{"businessId":{"type":"string"},"name":{"type":"string"},"permittedTasks":{"type":"array","items":{"type":"string"},"description":"Tasks the partner holds, in the bare spelling the grant takes (ADVERTISE, ANALYZE, MANAGE, ...). Meta reads them back with a PROFILE_PLUS_ prefix, which is stripped here; partners granted in Business Settings may hold tasks beyond the six the grant accepts, such as MANAGE_LEADS or REVENUE."}}},"MetaAssignedUser":{"type":"object","properties":{"id":{"type":"string","description":"Business-scoped user id."},"name":{"type":"string"},"tasks":{"type":"array","items":{"type":"string"}}}},"MetaBusinessUser":{"type":"object","properties":{"id":{"type":"string","description":"Business-scoped user id."},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","description":"Meta role in the portfolio, e.g. ADMIN or EMPLOYEE."}}},"CreateMetaAdAccountRequest":{"type":"object","additionalProperties":false,"required":["accountId","businessId","name","currency","timezoneId"],"properties":{"platform":{"type":"string","enum":["meta"],"description":"Optional. Omit it or send meta for a Meta ad account."},"accountId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio metaads SocialAccount ID."},"businessId":{"type":"string","pattern":"^[1-9][0-9]*$","description":"Business portfolio that will own the account."},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Ad account name. Whitespace is trimmed."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"Uppercase ISO 4217 currency supported by Meta."},"timezoneId":{"type":"integer","minimum":0,"maximum":4294967295,"description":"Numeric Meta timezone ID from the linked timezone list. For example 1 is America/Los_Angeles."},"endAdvertiser":{"type":"string","pattern":"^(NONE|[1-9][0-9]*)$","default":"NONE","description":"End advertiser business or page ID. NONE uses the owning business."},"mediaAgency":{"type":"string","pattern":"^(NONE|[1-9][0-9]*)$","default":"NONE","description":"Media agency business or page ID. NONE for self-serve customers."},"partner":{"type":"string","pattern":"^(NONE|[1-9][0-9]*)$","default":"NONE","description":"Partner business or page ID. NONE for self-serve customers."},"invoice":{"type":"boolean","description":"Request Meta invoicing. Eligibility is determined by Meta."},"invoiceGroupId":{"type":"string","pattern":"^[1-9][0-9]*$","description":"Existing Meta invoice group ID."},"invoicingEmails":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","format":"email"},"description":"Addresses for Meta invoices."},"io":{"type":"boolean","description":"Meta insertion-order invoicing option."},"poNumber":{"type":"string","minLength":1,"maxLength":255,"description":"Purchase order number."},"fundingId":{"type":"string","pattern":"^[1-9][0-9]*$","description":"Existing Meta funding reference. Does not add a payment method."},"adAccountCreatedFromBmFlag":{"type":"boolean","description":"Meta Business Manager creation flag."}}},"CreateGoogleAdAccountRequest":{"type":"object","additionalProperties":false,"required":["platform","accountId","managerCustomerId","name","currency","timeZone"],"properties":{"platform":{"type":"string","enum":["google"]},"accountId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio googleads SocialAccount ID whose Google user reaches the manager."},"managerCustomerId":{"type":"string","pattern":"^[0-9]+$","description":"Manager (MCC) customer id without dashes. The new account is created under it. List reachable managers with GET /v1/ads/accounts/hierarchy."},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Account name. Whitespace is trimmed."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"Uppercase ISO 4217 currency. Cannot be changed after creation."},"timeZone":{"type":"string","description":"IANA time zone name, for example Europe/Madrid. Cannot be changed after creation."},"validateOnly":{"type":"boolean","default":false,"description":"Ask Google to validate the request without creating the account."}}},"CreatedMetaAdAccount":{"type":"object","required":["adAccountId","businessId","connectionUpdated","paymentMethodRequired","adsManagerUrl","nextSteps","warnings"],"properties":{"adAccountId":{"type":"string","pattern":"^act_[0-9]+$","description":"New Meta ad account ID for subsequent ads calls."},"businessId":{"type":"string","description":"Owning business portfolio ID."},"connectionUpdated":{"type":"boolean","description":"Whether the connection scope and discovery schedule were updated."},"paymentMethodRequired":{"type":"boolean","description":"Always true as a delivery prerequisite. This is not a live funding-source check. Confirm payment or invoicing in Ads Manager."},"adsManagerUrl":{"type":"string","format":"uri","description":"Open the created account in Ads Manager."},"nextSteps":{"type":"string","description":"Payment setup instructions for the user."},"warnings":{"type":"array","items":{"type":"string"},"description":"Recovery instructions if the account could not be attached to the connection."}}},"CreatedGoogleAdAccount":{"type":"object","required":["platform","adAccountId","managerCustomerId","connectionUpdated","warnings","paymentMethodRequired","nextSteps","validateOnly"],"properties":{"platform":{"type":"string","enum":["google"]},"adAccountId":{"type":"string","pattern":"^[0-9]+$","description":"New Google Ads customer id for subsequent ads calls."},"managerCustomerId":{"type":"string","description":"Manager the account was created under."},"connectionUpdated":{"type":"boolean","description":"Whether the customer was added to the connection and discovery was scheduled. When false the account exists: reconnect Google Ads instead of creating it again."},"warnings":{"type":"array","items":{"type":"string"},"description":"Recovery instructions if the account could not be attached to the connection."},"paymentMethodRequired":{"type":"boolean","description":"Always true. The account has no billing until it is set up in Google Ads."},"nextSteps":{"type":"string","description":"Billing setup instructions for the user."},"validateOnly":{"type":"boolean","description":"Always false on a 201."}}},"CommentAttachment":{"type":"object","description":"The media on a comment or reply, one per comment (the first item when the platform returns several).\n`type` is the platform's own media kind:\n\n- Facebook: sticker, animated_image_share, photo, image_share, share or video_inline.\n- TikTok: image.\n- X: photo, video or animated_gif. A video `url` is an mp4 and `imageUrl` its preview.\n- Threads: IMAGE, VIDEO or GIF. Album replies carry no attachment.\n- Bluesky: image, video or external (link cards, GIFs arrive this way). A video `url` is an HLS playlist (.m3u8).\n\nFacebook and Threads URLs are expiring Meta CDN links, so fetch promptly.\nInstagram, YouTube, LinkedIn and Reddit comments carry no media.\n","required":["type"],"properties":{"type":{"type":"string","description":"The platform's own media kind, see the schema description for each platform's values."},"imageUrl":{"type":"string","description":"Rendered image or preview URL."},"url":{"type":"string","description":"Source or playable URL. Facebook GIFs carry an l.facebook.com redirect, X videos an mp4, Bluesky videos an HLS playlist."}}},"LinkedInMentionIssue":{"type":"object","description":"One LinkedIn mention that could not be resolved, listed under `details.mentions[]` of the error.","required":["input","code","message"],"properties":{"input":{"type":"string","description":"The mention exactly as written in the request, for example `@[https://www.linkedin.com/in/jane-doe]`."},"code":{"type":"string","description":"Why it failed.","enum":["linkedin_mention_unresolvable","linkedin_mention_requires_page_admin","linkedin_mention_name_unavailable","linkedin_mentions_limit_exceeded","rate_limited","reconnect_required","temporarily_unavailable"]},"message":{"type":"string","description":"Human-readable reason."}}},"PinPostRequest":{"type":"object","required":["platform"],"properties":{"platform":{"type":"string","description":"Must be `facebook`. Any other value answers 400 `platform_not_supported`.","example":"facebook"},"accountId":{"type":"string","description":"Which Facebook account's copy to change when the post was published to several Facebook accounts. Required in that case."}}},"PinPostResponse":{"type":"object","properties":{"success":{"type":"boolean"},"pinned":{"type":"boolean","description":"Whether the post is now pinned to the top of the Page."},"platformPostId":{"type":"string","description":"The Facebook post ID that was changed."},"message":{"type":"string"}}},"ErrorResponse":{"type":"object","description":"Canonical error envelope. `error` is the human-readable message; `type`,\n`code`, `param`, `platform`, and `platformError` are top-level siblings\nfor programmatic handling. For upstream platform failures (`type:\nplatform_error`), `platformError` carries the provider's raw payload\nverbatim (for Meta: `error_subcode`, `error_user_title`, `error_user_msg`).\n","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."},"docUrl":{"type":"string","description":"Documentation page for resolving the error, when one applies."},"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\nintegrators can read provider-specific codes. For Meta this includes\nerror_subcode, error_user_title, and error_user_msg.\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional structured context for the error (for example field-level validation errors). What it carries depends on the endpoint and platform.\n\n**Meta ads refusals.** The ones customers hit most come back with their own `code` instead of `platform_api_error`, the field to fix in `param`, and an English `details.hint` saying how to fix it. `details.fix` ({ label, url }) links the Meta page that resolves it, when there is one.\n\nThe code is picked from Meta's numeric `code` and `error_subcode`, never from the message, so it is the same whatever language Meta wrote `error_user_msg` in. Branch on `code` and show `details.hint`.\n\n- `ad_account_payment_required`: the ad account has no usable payment method (subcode 1815010, 1359188).\n- `ad_account_policy_not_accepted`: a business admin has to accept Meta's non-discrimination policy (subcode 2859002, 2859024).\n- `lead_ads_terms_not_accepted`: the Facebook Page has not accepted the Lead Ads terms (subcode 1815089).\n- `verified_advertiser_required`: the market requires a verified beneficiary and payer; send `regionalRegulationIdentities` (subcode 3858634, 3858636, 3858442, 3858548, 3858495).\n- `ad_account_unusable`: the ad account is not active, or the business is restricted from advertising (subcode 1885316, 2446325, and 2490592, 4841021 below).\n- `meta_security_check_required`: the Facebook user behind the connection is held at a security check (code 31).\n- `meta_action_blocked`: Meta temporarily blocked the Facebook user from this action (subcode 2859015).\n- `meta_ad_consent_required`: the Page or Instagram owner chose Meta without ads or less personalized ads (subcode 3858231, 3858412).\n- `instagram_account_restricted`: Meta restricted the Instagram account the ad runs as (subcode 2207070).\n- `insufficient_permissions`: the ad account cannot use the Instagram account, or the Facebook user has no advertiser permission on the Page (subcode 1815199, 1815202, 1885499, 1341012, and the Advertise permission case below).\n- `whatsapp_number_not_linked`: the WhatsApp number is no longer linked to the Page (subcode 2446880).\n- `invalid_targeting`: Meta refused the audience or a placement (subcode 1487079, 1870247, 2909035, 1870189, 1870188, 1487756, 1487843, 2490562).\n- `post_not_boostable`: Meta does not allow the post to be promoted (subcode 2446187, 2875030, 1487472).\n- `budget_too_low`: the budget is below Meta's minimum, which `platformError.error_user_msg` states (subcode 1885272).\n- `meta_object_not_accessible`: Meta cannot load an object the request names (wrong ID, deleted, or no access); `platformError.message` names the ID (subcode 33, on ads routes only).\n\nMeta's own error stays in the message and in `platformError`.\n\n**Private replies.** `privateReplyConsumed` appears on the private-reply endpoint's 400 when the comment's single reply is already spent. `privateReplyOutcome: \"unknown\"` appears on its 502 when Meta answered a server error and the reply may have been delivered.\n\n**Google quota 429.** On a Google Ads or YouTube Analytics 429, `quotaExhausted: true` marks the failure as Google's own quota, not a Zernio rate limit, so you can keep calling other platforms instead of backing off everywhere. When Google names the scope, `quotaScope` is also set:\n\n- `DEVELOPER`: the shared budget (the developer token for Google Ads, the Google Cloud project for YouTube Analytics). Every account on Zernio is affected and there is nothing to change on your side.\n- `ACCOUNT`: your own ad account (Google Ads only).\n\nA Meta 429 carries neither field.\n\n**Zernio Google Ads burst-limit 429.** Carries `budgetScope` instead, never `quotaExhausted`. These are Zernio's own limits, applied before the call reaches Google, and both clear within a minute. They are separate axes from `quotaScope`, not the same pool named twice.\n\n- `account`: the limit of 15 requests per minute per connected Google Ads account.\n- `user`: the ceiling of 120 requests per minute per Zernio user across all their Google Ads accounts.\n\n**Failed Meta ad create** (`POST /v1/ads/create`, `POST /v1/ads/boost`, `POST /v1/ads/ctwa`). Carries `stage` (where it failed), `adAccountId` (on which ad account) and `createdObjects` (every object this request had already created, with what cleanup did to it).\n\n- `left_behind` objects still exist on the ad account (Meta refused the delete, typically on a held account, or the delete hit a network error). Delete them yourself or reuse them.\n- `unconfirmedWrite` is set when Meta answered a create with a 5xx or a non-JSON body, or dropped the connection, and Zernio could not confirm whether the object exists. Check that parent before creating it again.\n\n**Ineligible ad account: 422 `ad_account_unusable`.** When Meta refuses a write because the ad account's status is ineligible to manage ads (Meta subcode 2490592 or 4841021, on the write itself or on a cleanup delete), any Meta ads write answers it.\n\nThat covers create, boost, CTWA, campaign / ad set / ad updates and status changes.\n\nThe message names the ad account when known, links Meta's fix (https://www.facebook.com/business/help/422289316306981), lists the objects left behind and ends with Meta's original error, which also stays verbatim in `platformError`.\n\nMeta often reports the first failure under an unrelated code (e.g. 1487194 on the creative), so branch on `code`, not on `platformError`.\n\n**Missing Advertise permission: 403 `insufficient_permissions`.** When the Facebook user behind the connection's token lacks the Advertise permission on the ad account, any Meta ads write answers it.\n\nTriggers: Meta subcode 2490585, 2490591 or 4841020 on the write, or a code 200 refusal such as 1487194 whose cleanup deletes Meta refused with 2490591 or 4841020.\n\nMeta may still accept the campaign and ad set and refuse only the ad. The message names the ad account, asks for the Advertise or Manage permission on it (or a token granted `ads_management`, by reconnecting) and lists the objects left behind.\n\nIt ends with Meta's `error_user_title`, `error_user_msg` and subcode; the raw error stays in `platformError`.\n","properties":{"stage":{"type":"string","enum":["media","campaign","adset","creative","ad","activation","other"],"description":"Meta ad create failures only. The step that failed:\n\n- `media`: image/video download or upload.\n- `campaign`\n- `adset`\n- `creative`\n- `ad`: the ad POST itself, where Meta's code 31 / 3858385 hold and 100 / 1359188 payment rejections land.\n- `activation`: switching the created objects on. No longer returned: a refused switch to ACTIVE now answers 201 with an `activation_failed:` warning and the objects kept PAUSED.\n- `other`: a read or check before any write.\n"},"adAccountId":{"type":"string","description":"Meta ad create failures only. The ad account the request wrote to (`act_...`)."},"createdObjects":{"type":"array","description":"Meta ad create failures only. Every object this request created before failing, in creation order. Objects you referenced (an existing campaign, ad set, creative or video) are never listed and never deleted.","items":{"type":"object","properties":{"type":{"type":"string","enum":["campaign","adset","creative","ad","video","image"]},"id":{"type":"string","description":"Meta object id; for `image` the image hash."},"cleanup":{"type":"string","enum":["deleted","left_behind","kept"],"description":"- `deleted`: Zernio deleted it.\n- `left_behind`: cleanup could not delete it (Meta refused the delete, or the delete hit a network error), so it still exists.\n- `kept`: deliberately not deleted. Either an image (hashes are shared by every upload of the same file), or an object Zernio found by name after Meta lost its answer to the create, which may belong to another request with the same name.\n"}}}},"unconfirmedWrite":{"type":"object","description":"Meta ad create failures only. Set when Meta answered a create with a 5xx or a non-JSON body, or dropped the connection after the request was sent, and reading the parent back by name did not settle it. Zernio did not retry it.\n\nOne of these left it open:\n\n- The read-back found several objects of the same name.\n- The parent could not be read, or the object is a creative, which has no reliable read-back.\n- The read-back found no such object, after a dropped connection, a non-JSON body, a 5xx with `retryOnServerError: false`, or a 5xx on a create whose own body is `status: ACTIVE`.\n","properties":{"type":{"type":"string","enum":["campaign","adset","creative","ad"]},"parentId":{"type":"string","description":"Where to look for it: the ad set for an ad, the campaign for an ad set, the ad account otherwise."}}},"quotaExhausted":{"type":"boolean","description":"Google Ads and YouTube Analytics 429 only. True when the upstream Google quota is spent rather than a Zernio limit."},"quotaScope":{"type":"string","enum":["DEVELOPER","ACCOUNT"],"description":"Google Ads and YouTube Analytics 429 only, when the scope is known. DEVELOPER is the shared budget (the developer token for Google Ads, the Google Cloud project for YouTube Analytics); ACCOUNT is your ad account (Google Ads only)."},"budgetScope":{"type":"string","enum":["account","user"],"description":"Zernio Google Ads burst-limit 429 only (never set alongside `quotaExhausted`). `account` is the limit of 15 requests per minute per connected Google Ads account; `user` is the ceiling of 120 requests per minute per Zernio user across all their Google Ads accounts. Both clear within a minute."}}}}},"CommentAutomationAudience":{"type":"object","description":"Who a comment automation answers. Instagram only - Meta exposes the follow\nrelationship on no other platform, and only for people who have MESSAGED the\naccount (a comment grants no consent). `whenUnknown` is therefore the important\nsetting: it decides what happens for a first-time commenter.\n","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.\n\n- `send` (default): deliver the DM anyway (fails open).\n- `skip`: stay silent.\n- `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.\n\nWith `verify`, the tap re-checks the follow relationship live, with no cached answer. A known non-follower gets `followGate.notFollowingMessage`, never the DM. If Instagram still will not reveal the relationship on the tap, or the lookup fails, the DM is delivered (fails open).\n"},"tapToUnlock":{"type":"boolean","default":false,"description":"Instagram only. Send `followGate.message` with its button to EVERY commenter and deliver the real DM when they tap it, with no follow check at any point.\n\nCannot be combined with a `followerStatus` other than `any` or with `minFollowerCount` (400); `whenUnknown` is ignored. A PATCH that sends `audience` without this field clears it.\n"}}},"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 or tapToUnlock=true. The default copy asks for a follow under whenUnknown=verify and only for the tap under tapToUnlock."},"buttonLabel":{"type":"string","maxLength":20,"description":"Confirm button label. Defaults to \"I'm following\" (whenUnknown=verify) or \"Unlock\" (tapToUnlock)."},"profileButtonLabel":{"type":"string","minLength":1,"maxLength":20,"description":"Optional. When set, the follow gate DM and the not-following message with the confirm button also carry a URL button with this label that opens the connected Instagram account's profile. Omit for the confirm button only. Instagram only."},"notFollowingMessage":{"type":"string","maxLength":1000,"description":"Sent to a commenter we know does not follow (followerStatus=follower), and after a confirm tap that does not unlock the DM.\n\n- When following would unlock it, the message carries the confirm button so they can re-check once they follow. Above 640 characters it goes out as plain text without the button.\n- Omit to stay silent on a keyword comment. A confirm tap always gets an answer (a default message is used).\n"}}},"CommentAutomationRepeatPolicy":{"type":"object","description":"Whether a commenter can receive this automation's DM more than once.\n\n- `once` (default): one DM per person per door, ever.\n- `every_comment`: every new matching comment is eligible again; one comment is still answered at most once. `cooldownHours` suppresses a repeat to the same person within that many hours.\n","required":["mode"],"properties":{"mode":{"type":"string","enum":["once","every_comment"],"default":"once"},"cooldownHours":{"type":"integer","minimum":1,"maximum":8760,"description":"every_comment only (400 with once). Hours after a DM during which the same person is not DMed again."}}},"CommentAutomationActions":{"type":"object","description":"Actions taken on the matched comment itself (comment trigger only; ignored on the\nstory-reply and DM doors). They never block or fail the DM: when one cannot run,\nthe log row says why (`likeSkipped`, `hideSkipped`).\n","properties":{"likeComment":{"type":"boolean","description":"Like the comment as the account. Facebook always; Instagram only for accounts connected through Facebook Login and allowlisted for likes while Meta reviews the permission. Otherwise the like is skipped and logged."},"hideComment":{"type":"boolean","description":"Hide the comment once the first DM has been attempted, so the private reply is never sent to an already hidden comment."}}},"CommentAutomationDmMedia":{"type":"object","description":"An image, video, audio clip or file sent right after the DM text as a second message (a Meta message carries one body, so text and attachment are two sends).\n\nOn the comment trigger, Meta may refuse the second message until the commenter replies. The DM then still counts as sent and the log row carries `mediaError`.\n","required":["type","url"],"properties":{"type":{"type":"string","enum":["image","video","audio","file"]},"url":{"type":"string","format":"uri","description":"Publicly reachable http(s) URL Meta downloads the media from."}}},"CommentAutomationQuickReply":{"type":"object","required":["title","payload"],"properties":{"title":{"type":"string","maxLength":20},"payload":{"type":"string","description":"Delivered back via the messaging webhook when tapped."},"imageUrl":{"type":"string","format":"uri"}}},"CommentAutomationStats":{"type":"object","description":"Running counters for the automation.","properties":{"triggered":{"type":"integer","description":"Matched triggers that reached the audience or send stage."},"dmsSent":{"type":"integer"},"dmsFailed":{"type":"integer"},"uniqueContacts":{"type":"integer"},"trackedSends":{"type":"integer","description":"DMs sent with a trackable (wrapped) link. CTR denominator: divide clicks by this, not dmsSent. Lags dmsSent for campaigns that predate click tracking."},"linkClicks":{"type":"integer","description":"Total clicks on tracked links (bots/prefetch excluded)."},"uniqueClicks":{"type":"integer","description":"Distinct people who clicked a tracked link."},"delivered":{"type":"integer","description":"DMs confirmed delivered (Messenger; IG emits no delivery receipt)."},"read":{"type":"integer","description":"DMs confirmed read (IG messaging_seen / Messenger message_reads)."},"audienceSkipped":{"type":"integer","description":"Triggers the audience rule did not answer with the DM."},"followGateSent":{"type":"integer"},"followGatePassed":{"type":"integer"},"followGateFailed":{"type":"integer"}}},"CommentAutomationLog":{"type":"object","properties":{"id":{"type":"string"},"commentId":{"type":"string"},"commenterId":{"type":"string"},"commenterName":{"type":["string","null"]},"commenterUsername":{"type":["string","null"]},"commentText":{"type":["string","null"]},"source":{"type":["string","null"],"enum":["comment","live_comment","story_reply","story_mention","dm",null],"description":"Which door triggered this send. Null on rows written before this field existed (all of those are comment-triggered)."},"status":{"type":"string","enum":["pending","sent","failed","skipped","gated"],"description":"DM outcome:\n\n- 'pending': the automation has a dmDelaySeconds and the response is queued but not sent yet.\n- 'gated': the follow-gate confirmation DM went out and we are waiting for the tap. It flips to 'sent' or 'skipped' when they tap.\n- 'skipped': also covers repeatPolicy, cooldown and dedupeSameTextHours suppressions, with the reason in error."},"audienceOutcome":{"type":["string","null"],"enum":["passed","blocked","gate_sent","gate_passed","gate_failed",null],"description":"How the audience rule resolved. Null on automations without one."},"gateButtonStatus":{"type":["string","null"],"enum":["delivered","rejected","omitted",null],"description":"Whether the follow-gate button reached the commenter: 'rejected' = Meta refused the gate DM, 'omitted' = the prompt went out as plain text because it was over 640 characters. Null when no gate DM was sent."},"commenterIsFollower":{"type":["boolean","null"],"description":"Follow relationship at decision time. Null when Instagram would not tell us (the commenter never messaged the account)."},"commenterFollowerCount":{"type":["integer","null"]},"gateResolvedAt":{"type":["string","null"],"format":"date-time","description":"When the follow-gate tap was claimed."},"error":{"type":["string","null"],"description":"DM error message when status is failed, or the reason when it is skipped."},"platformError":{"type":["object","null"],"description":"Platform error codes of the failed DM (Meta `code` and `error_subcode`), when the platform sent them. Null on successful rows and on rows written before this field existed.","properties":{"code":{"type":"integer"},"subcode":{"type":"integer"}}},"privateReplyConsumed":{"type":["boolean","null"],"description":"True when the failed send spent the comment's single private reply (Instagram subcode 1545133 or 2534023, or Meta code 10900 on Instagram and Facebook), the same rule as `details.privateReplyConsumed` on the private-reply endpoint. Null on direct DMs and on rows written before this field existed."},"commentReplyStatus":{"type":["string","null"],"enum":["pending","sent","failed","skipped",null],"description":"Outcome of the optional public reply on the triggering comment. With publicReplyPolicy after_dm, 'skipped' if no commentReply was configured or if the DM failed (the public reply is not attempted in that case)."},"commentReplyError":{"type":["string","null"],"description":"Public-reply error message if commentReplyStatus is failed"},"publicReplyPostedAt":{"type":["string","null"],"format":"date-time","description":"When the public reply was posted. Null when it was not."},"likeSkipped":{"type":["string","null"],"description":"Why actions.likeComment did not like the comment. Null when it did or was not configured."},"hideSkipped":{"type":["string","null"],"description":"Why actions.hideComment did not hide the comment. Null when it did or was not configured."},"mediaError":{"type":["string","null"],"description":"Why the dmMedia follow-up was not delivered. The DM itself still counts as sent."},"nextDueAt":{"type":["string","null"],"format":"date-time","description":"When the next queued send fires. Present only while something is still pending."},"clickedAt":{"type":["string","null"],"format":"date-time","description":"This recipient's first click on a tracked link (what uniqueClicks counts)."},"clickCount":{"type":"integer","description":"This recipient's total clicks on tracked links."},"createdAt":{"type":"string","format":"date-time"}}},"DmButton":{"type":"object","description":"A single inline button rendered inside an auto-DM via Meta's button_template.\nUp to 3 buttons per automation. `url` and `postback` work on Instagram and\nFacebook; `phone` is Facebook-only. When buttons are set, `dmMessage` becomes\nthe button_template text and must be 640 characters or less.\n","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. Works on every Instagram and Facebook trigger.\n\nIt 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`.\n\nMutually exclusive with `buttons` (sending both is a 400). Up to 10 elements, rendered as a horizontally swipeable carousel. Rendering confirmed on the Instagram and Messenger mobile apps.\n","required":["type","elements"],"properties":{"type":{"type":"string","enum":["generic"]},"imageAspectRatio":{"type":"string","enum":["horizontal","square"],"description":"Facebook only. How Messenger renders each element imageUrl: horizontal (1.91:1, the default) or square (1:1). Instagram has no such setting, so an Instagram automation carrying it is a 400."},"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.\nTransitions `pending → active` when the inbound webhook receives a reply\nfrom the matching phone (the reply itself proves ownership).\n","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\n`active`. Expired sessions are pruned by TTL and never appear in\nlist responses.\n"},"expiresAt":{"type":"string","format":"date-time","description":"UTC timestamp at which the session becomes invalid. Pending sessions\nget a 24h window; activated sessions get 7 days.\n"},"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."},"segmentMetricsAvailable":{"type":"boolean","description":"Whether YouTube returned startedWatching and stoppedWatching for this curve. When false, both are 0 placeholders in every point, not measured values."},"retentionCurve":{"type":"array","description":"Up to 100 points covering the video timeline, aggregated over the date range. Contains only the buckets YouTube reports for that range and is never zero-filled, so it can end before 1.0, skip positions, or be empty.","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. A 0 placeholder when segmentMetricsAvailable is false."},"stoppedWatching":{"type":"integer","description":"Viewers who stopped watching in this segment. A 0 placeholder when segmentMetricsAvailable is false."},"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\nanalytics endpoint (/v1/analytics/{facebook|instagram|youtube|linkedin|tiktok}/*).\nThe name is historical - the shape was first shipped for Instagram and every\nnew platform endpoint reuses it for response-shape consistency. The platform\nfield echoes back which platform served the response.\n","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.\n\n- For time_series: each metric has \"total\" (number) and \"values\" (array of {date, value}).\n- For total_value: each metric has \"total\" (number) and optionally \"breakdowns\" (array of {dimension, value}).\n\n**Monetary metrics** also carry \"unit\" and \"currency\". Zernio never rescales money: \"total\" and every \"values[].value\" are the platform's raw numbers in the stated unit.\n\nMonetary metrics keep \"values\" even on metricType=total_value, because their \"total\" is the sum of the daily buckets the platform returned over the range. Keep the series to reconcile that sum against the platform's own reporting before invoicing on it.\n\nA 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.\n","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.\n\n- \"micro_amount\": the platform returned an object carrying a micro amount; values are that integer, summed, unconverted. Zernio publishes no divisor because Meta documents none: divide by the scale you verified against the Page's own Meta Business Suite export. On Facebook Page insights this is always content_monetization_earnings.\n- \"unspecified\": the platform returned a bare number with no unit metadata, 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.\n"},"currency":{"type":["string","null"],"description":"ISO 4217 currency of a monetary metric, or null when the platform omitted it.\nAlways null on monetization_approximate_earnings, which Meta returns as a bare number\nwith no currency; always present on content_monetization_earnings.\n","example":"USD"}}}},"unavailableMetrics":{"type":"array","description":"Requested metrics that could not be served. Present only when at least one metric is unavailable, absent otherwise.\n\nEach 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.\n","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":"Why the metric is unavailable:\n\n- \"not_enrolled\": the account is not enrolled in the program behind this metric.\n- \"permission_missing\": the connected user lacks access to this metric.\n- \"unsupported_metric\": the platform does not accept this metric name on the API version Zernio uses.\n- \"no_data\": the platform returned no bucket for this metric over the requested range.\n- \"unreadable_value\": the platform returned a value shape Zernio cannot read, so no total is reported.\n- \"mixed_currency\": readable values disagree on currency or unit within the range.\n- \"upstream_error\": any other platform failure.\n\n\"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.\n"},"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\nsame unavailable-vs-zero contract as the Page-level response; there is no date range, no\nmetricType, and no daily \"values\", because the single lifetime bucket IS the total.\n","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\nacross dates or across posts.\n"},"metrics":{"type":"object","description":"One entry per served metric. A metric reported here with \"total\": 0 genuinely earned\nnothing (or its Page is not enrolled, which Meta reports identically).\n","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\nthat integer, unconverted. Zernio does not publish a divisor because Meta does not\ndocument one; divide by the scale you have verified against the Page's own Meta\nBusiness Suite export. This is always content_monetization_earnings.\n\n\"unspecified\": Meta returned a bare number with no unit metadata, passed through as-is;\nMeta does not state whether it is major or minor currency units. This is always\nmonetization_approximate_earnings.\n"},"currency":{"type":["string","null"],"description":"ISO 4217 currency, or null when Meta omitted it. Always null on\nmonetization_approximate_earnings; always present on content_monetization_earnings.\n","example":"USD"}}}},"unavailableMetrics":{"type":"array","description":"Requested metrics Meta could not serve. Present only when at least one metric is\nunavailable, and absent otherwise. Each listed metric is OMITTED from \"metrics\" rather than\nreported as 0. The request itself still succeeds with HTTP 200.\n","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":"Why the metric is unavailable:\n\n- \"not_enrolled\": the account is not enrolled in the program behind this metric.\n- \"permission_missing\": the connected user lacks access to this metric.\n- \"unsupported_metric\": Meta does not accept this metric name on the API version Zernio uses.\n- \"no_data\": Meta returned no bucket for this metric.\n- \"unreadable_value\": Meta returned a value shape Zernio cannot read, so no total is reported.\n- \"mixed_currency\": readable values disagree on currency or unit.\n- \"upstream_error\": any other platform failure.\n\n\"no_data\" is the common case in practice; the others are defensive.\n"},"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.permissions_changed","account.ads.initial_sync_completed","account.ads.sync_failed","account.ads.sync_recovered","analytics.synced","post.tracking_completed","post.authenticity_changed","message.received","conversation.started","conversation.control_changed","call.received","call.ended","call.failed","call.permission_request","message.sent","message.edited","message.deleted","message.delivered","message.read","message.played","message.failed","reaction.received","referral.received","comment.received","review.new","review.updated","review.deleted","review.restored","lead.received","ad.status_changed","ad.created","ad.updated","campaign.created","campaign.updated","ad.review.approved","ad.review.rejected","ad.delivery_issue","campaign.budget.depleted","ad_account.status_changed","ad.video.processed","ad_rule.triggered","automation.check.completed","automation.action.applied","automation.action.failed","automation.action.unknown","automation.alert.opened","automation.alert.escalated","automation.alert.resolved","whatsapp.template.status_updated","whatsapp.template.category_updated","whatsapp.account.name_status_updated","whatsapp.account.quality_updated","whatsapp.account.status_updated","whatsapp.account.alert_received","whatsapp.contact.identity_changed","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","phone_number.stock_available","verification.approved","verification.failed","api.changelog.published","sms.registration.action_required","sms.registration.status_updated","branded_calling.identity.status_updated","branded_calling.identity.action_required","branded_calling.number.status_updated","rcs.agent.status_updated","commerce.product.created","commerce.product.updated","commerce.product.deleted","commerce.order.created","commerce.order.updated","commerce.order.refunded","contact.tag_added","contact.tag_removed","contact.field_changed","sequence.enrolled","sequence.exited","workflow.run.started","workflow.run.completed","workflow.run.failed","support.run.completed","support.run.failed","campaign_submission.received","campaign_submission.flagged","campaign_submission.pending_review","campaign_submission.approved","campaign_submission.rejected","creator_campaign.budget_exhausted","creator_campaign.closed","campaign_payout.payable","campaign_payout.settled","campaign_payout.failed","campaign_participant.joined","campaign_participant.suspended","campaign_participant.removed","account.rate_limited","calendar.event.created","calendar.event.updated","calendar.event.deleted","file.created","file.updated","file.deleted","file.picked","contact.updated","contact.deleted"]},"description":"Events subscribed to"},"isActive":{"type":"boolean","description":"Whether webhook delivery is enabled"},"lastFiredAt":{"type":"string","format":"date-time","description":"Timestamp of the last successful webhook delivery. On a healthy endpoint it is refreshed at most once every 10 minutes, so it can trail the most recent delivery by up to 10 minutes."},"failureCount":{"type":"integer","description":"Consecutive terminal delivery failures. Resets to 0 on any successful delivery.\n\nAuto-disable triggers only when the endpoint has had no successful delivery within a 3-day window AND either reaches 20 consecutive terminal failures or has been failing continuously for 3 days. Any success within that window keeps the endpoint enabled, regardless of the count.\n"},"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","commerce","creator_campaigns","money","calendar","files"]},"description":"Resource groups this subscription does not receive (opt-out denylist, same vocabulary and semantics as the field on API keys).\n\n- Absent or empty: the subscription receives every event in `events` (how subscriptions created before this field behave).\n- An event whose group is listed is dropped before delivery, even when still in `events`. The same check runs on every replay path (test fire, redelivery, dead-letter requeue).\n- Edits apply 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.\n"},"profileIds":{"type":"array","items":{"type":"string"},"description":"Profiles this subscription receives events for (allowlist). Absent or empty means every profile, which is how every subscription created before this field existed behaves.\n\n- A scoped subscription only gets events attributable to a listed profile.\n- An aggregate `post.*` event is attributed to the profile of every account the post targets, so a post spanning two scoped endpoints' profiles reaches both.\n- Events with no profile behind them (`verification.*`, `phone_number.*`, a legacy post whose accounts were deleted) are not delivered to it.\n\nApplied when the event is emitted: a redelivery replays a delivery already made to this endpoint, and a test fire ignores the list.\n"},"accountIds":{"type":"array","items":{"type":"string"},"description":"Connected accounts this subscription receives events for (allowlist). Absent or empty means every account.\n\n- Same semantics as `profileIds`, keyed on the account: an aggregate `post.*` event is attributed to every account the post targets.\n- Events that name no connected account (`verification.*`, `phone_number.*`, and `whatsapp.number.*`, which carry the phone number) are not delivered to an account-scoped subscription.\n- A subscription with both lists must be satisfied on both.\n- Applied when the event is emitted. A redelivery replays a delivery already made to this endpoint, and a test fire ignores the list.\n- The shared WhatsApp sandbox account id (listed by `GET /v1/accounts?includeSandbox=true`) is accepted, so a subscription can receive sandbox traffic only.\n"}}},"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: the payload `id`, also sent as the X-Zernio-Event-Id header. Shared by every attempt and redelivery of the same event."},"event":{"type":"string","description":"Event type that triggered the delivery (e.g. post.published)"},"test":{"type":"boolean","description":"true when the delivery was a sample fired by POST /v1/webhooks/test with an event, not a real event. Absent otherwise."},"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"}}},"WebhookProfiles":{"type":"array","description":"The profiles this event belongs to, each with the externalId you set on it (null when none is set). Use it to route the event to your tenant without storing Zernio profile ids.\n\nPresent on every event tied to a profile, absent on events that belong to none. Events spanning several profiles (a post published to accounts of different profiles) list each once.\n","items":{"type":"object","required":["id","externalId"],"properties":{"id":{"type":"string"},"externalId":{"type":["string","null"],"example":"tenant_42"}}}},"WebhookPayloadPost":{"type":"object","description":"Webhook payload for post events","required":["id","event","post","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"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"},"errorCategory":{"type":"string","enum":["auth_expired","user_content","user_abuse","account_issue","platform_rejected","platform_error","platform_rate_limit","quota_exhausted","system_error","unknown"],"description":"Present when this target failed. Same taxonomy as `platforms[].errorCategory` on GET /v1/posts."},"errorSource":{"type":"string","enum":["user","platform","system"],"description":"Present when this target failed. Who must act: user, platform or system (Zernio)."},"platformError":{"$ref":"#/components/schemas/PostPlatformError"}}}},"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","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadPostPlatform":{"type":"object","description":"Webhook payload for these per-platform events:\n\n- `post.platform.published` and `post.platform.failed`: terminal events.\n- `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).\n- `post.tiktok.url_resolved`: same shape, fired when a published TikTok post's public URL is backfilled.\n\nTerminal events fire once per platform target inside a post as that platform reaches a terminal state (published or permanent failure). Exception: a target that later fails background reconciliation emits `post.platform.failed` a second time, after its own `post.platform.published`.\n\n**Blocks**: the `post` envelope mirrors `WebhookPayloadPost` so consumers can reuse rendering logic; `platform` identifies which specific platform transitioned; `account` identifies the connected account behind that platform-write.\n","required":["id","event","post","platform","account","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"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`\nif other platforms haven't terminated; check this field\nrather than assuming.\n"},"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"},"errorCategory":{"type":"string","enum":["auth_expired","user_content","user_abuse","account_issue","platform_rejected","platform_error","platform_rate_limit","quota_exhausted","system_error","unknown"],"description":"Present when this target failed. Same taxonomy as `platforms[].errorCategory` on GET /v1/posts."},"errorSource":{"type":"string","enum":["user","platform","system"],"description":"Present when this target failed. Who must act: user, platform or system (Zernio)."},"platformError":{"$ref":"#/components/schemas/PostPlatformError"}}}},"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 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."},"errorCategory":{"type":"string","enum":["auth_expired","user_content","user_abuse","account_issue","platform_rejected","platform_error","platform_rate_limit","quota_exhausted","system_error","unknown"],"description":"Error category for programmatic handling. Present on `failed` only. Same taxonomy as `platforms[].errorCategory` on GET /v1/posts."},"errorSource":{"type":"string","enum":["user","platform","system"],"description":"Who must act on the failure: user (fix content or reconnect), platform (outage or policy), system (Zernio). 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 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","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadAccountConnected":{"type":"object","description":"Webhook payload for account connected events","required":["id","event","account","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"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","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"OwnedPhoneNumber":{"type":"object","description":"A number you bought or ported. Null fields are omitted, except `socialAccountId` and `ownerAccountId`. Credentials stored for the number (such as the SIP digest password) are never returned; `sipAuthUsername` is the only SIP credential field exposed.","properties":{"_id":{"type":"string"},"phoneNumber":{"type":"string"},"country":{"type":"string"},"numberType":{"type":"string","description":"For example local, mobile, national or toll_free."},"status":{"type":"string","enum":["pending_payment","pending_regulatory","regulatory_declined","provisioning","verifying","active","suspended","releasing","released"]},"profileId":{"description":"The profile the number belongs to: `{ _id, name }` when the profile exists, otherwise its id.","oneOf":[{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":["string","null"]}}},{"type":"string"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"telnyxOrderId":{"type":["string","null"],"description":"Present once the number order has been placed (i.e. the requirement group was approved). Absent while still in identity review."},"telnyxAdvancedOrderId":{"type":"string","description":"Present on a pre-order: the carrier request placed for a number with no stock yet."},"registrantName":{"type":["string","null"],"description":"For regulated numbers, who it's registered for (company or person), set from the submitted KYC."},"endUserFirstName":{"type":["string","null"]},"endUserLastName":{"type":["string","null"]},"regulatoryDeclineReason":{"type":["string","null"],"description":"Reviewer rejection reason when status is regulatory_declined."},"regulatoryReviewComment":{"type":"string","description":"The latest reviewer comment on a regulated number still in review."},"regulatoryInfoStatus":{"type":"string","description":"`action_required` when the reviewer is waiting on you."},"onfidoVerificationUrl":{"type":["string","null"],"description":"For regulated (Tier 3/4) numbers with an Onfido ID-verification step: the link to forward to the end user. Set once the order is placed; null otherwise. Poll this field after submitting KYC."},"verifyUrl":{"type":["string","null"],"description":"Stable redirect to the live Onfido session. Prefer it over `onfidoVerificationUrl`, since it always resolves to a fresh session."},"onfidoOpened":{"type":"boolean","description":"True once the verify link has been opened at least once."},"metaPreverifiedId":{"type":"string"},"metaVerificationStatus":{"type":"string","enum":["pending","code_requested","verified","expired"]},"metaVerifiedAt":{"type":"string","format":"date-time"},"metaVerificationExpiresAt":{"type":"string","format":"date-time"},"metaPoolAddRejectedAt":{"type":"string","format":"date-time","description":"Set when WhatsApp reported the number as registered to another WhatsApp account while connecting it. The number keeps working for Calls and SMS; remove it from the other account and connect again, or replace it with POST /v1/whatsapp/phone-numbers/{id}/replace. Absent once WhatsApp accepts the number."},"socialAccountId":{"type":["string","null"],"description":"The WhatsApp account the number is linked to; null when WhatsApp is not connected."},"ownerAccountId":{"type":["string","null"],"description":"The telephony account that owns Calls and SMS on the number."},"sipTrunkId":{"type":["string","null"],"description":"SIP trunk the number is attached to; null when not trunked. While attached, enabling Calls or WhatsApp calling, requesting WhatsApp verification, and releasing the number all return 409."},"whatsAppRequested":{"type":"boolean","description":"False for a standalone phone bought for Calls or SMS only."},"smsRequested":{"type":"boolean"},"provisionedAt":{"type":"string","format":"date-time"},"activatedAt":{"type":"string","format":"date-time"},"connectedAt":{"type":"string","format":"date-time"},"suspendedAt":{"type":"string","format":"date-time"},"releasedAt":{"type":"string","format":"date-time"},"signupError":{"type":"string","description":"Meta's Embedded Signup error from the last failed connect attempt (raw text, often localized)."},"signupErrorAt":{"type":"string","format":"date-time"},"signupErrorStep":{"type":"string"},"monthlyCents":{"type":"integer","description":"What this number bills each month, in cents. Stamped when the number was bought, so an existing number keeps its price when the rate card changes."},"hostedByZernio":{"type":"boolean","description":"False for numbers you brought yourself (connected via Meta embedded signup). They live on your own carrier, so SMS/Calls can't be enabled on them."},"smsCapable":{"type":"boolean","description":"Whether the number can send SMS. Absent while unknown."},"mmsCapable":{"type":"boolean","description":"Whether the number can send MMS. Absent while unknown."},"domesticOnly":{"type":"boolean","description":"True when the number can only text numbers in its own country. Absent while unknown."},"smsRegistrationPending":{"type":"boolean","description":"True while a 10DLC registration covering this number is in review."},"smsSendApproved":{"type":"boolean","description":"True when outbound SMS is unlocked: an approved 10DLC covers the number, or the number is outside the US."},"smsBrandName":{"type":["string","null"],"description":"Brand of the 10DLC registration covering the number."},"features":{"type":"object","properties":{"calls":{"type":"boolean"},"whatsapp":{"type":"boolean"},"smsPending":{"type":"boolean"}}},"callingEnabled":{"type":"boolean","description":"Whether WhatsApp Business Calling is enabled on this number (manage via /v1/whatsapp/phone-numbers/{id}/calling)."},"forwardTo":{"type":"string","description":"WhatsApp calling forward destination."},"sipAuthUsername":{"type":"string","description":"SIP digest username for a sip: forward destination. The password is never returned."},"callerIdVerifiedAt":{"type":"string","format":"date-time"},"maxCallDurationSeconds":{"type":"integer"},"recordingEnabled":{"type":"boolean"},"transcriptionEnabled":{"type":"boolean"},"transcriptionLanguage":{"type":"string","enum":["auto","en","es"]},"callIconCountries":{"type":"array","items":{"type":"string"}},"forwardCallerId":{"type":"string","enum":["business","caller"]},"pstnVoiceEnabled":{"type":"boolean","description":"Whether Calls (PSTN voice) is on."},"pstnForwardTo":{"type":"string"},"voicemailEnabled":{"type":"boolean"},"voicemailGreeting":{"type":"string"},"businessHoursEnabled":{"type":"boolean"},"businessHoursTimezone":{"type":"string"},"businessHours":{"type":"array","items":{"type":"object","properties":{"day":{"type":"integer"},"open":{"type":"string"},"close":{"type":"string"}}}},"blockedCallers":{"type":"array","items":{"type":"string"}},"ivrEnabled":{"type":"boolean"},"ivrPrompt":{"type":"string"},"ivrOptions":{"type":"array","items":{"type":"object","properties":{"digit":{"type":"string"},"forwardTo":{"type":"string"},"label":{"type":"string"}}}}}},"PhoneNumberStockWatch":{"type":"object","required":["id","country","countryName","numberType","createdAt"],"properties":{"id":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2."},"countryName":{"type":"string"},"numberType":{"type":["string","null"],"enum":["local","mobile","national","toll_free",null],"description":"The watched number type, or null when the watch covers every type in the country."},"areaCode":{"type":["string","null"],"description":"The watched area code (NDC), or null when the watch covers every area."},"createdAt":{"type":"string","format":"date-time"}}},"WebhookPayloadPhoneNumberStockAvailable":{"type":"object","description":"Webhook payload for phone_number.stock_available events","required":["id","event","stock","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["phone_number.stock_available"]},"stock":{"type":"object","required":["country","types"],"properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code of the watched country."},"types":{"type":"array","description":"Number types deliverable at sweep time. Only types with stock are listed.","items":{"type":"object","required":["numberType","availableCount"],"properties":{"numberType":{"type":"string","description":"local, mobile, national or toll_free."},"availableCount":{"type":"integer","description":"Deliverable numbers at sweep time; first come, first served."}}}},"areaCode":{"type":"string","description":"Set when the watch named an area: the area code (NDC) that is back in stock."},"areaName":{"type":"string","description":"The name of that area, when known."}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadAccountPermissionsChanged":{"type":"object","description":"Webhook payload for account.permissions_changed events: an account connected through your own OAuth app hit a missing permission and stays connected for its other areas.","required":["id","event","account","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it."},"event":{"type":"string","enum":["account.permissions_changed"]},"account":{"type":"object","required":["accountId","profileId","platform","username","oauthAppId","missingScopeAreas","reason"],"properties":{"accountId":{"type":"string"},"profileId":{"type":"string"},"platform":{"type":"string"},"username":{"type":"string"},"displayName":{"type":"string"},"oauthAppId":{"type":"string","description":"The OAuth app the account connected through."},"missingScopeAreas":{"type":"array","items":{"type":"string","enum":["posting","analytics","comments","messaging"]},"description":"Every area now missing. Enable the permission on your app (or have the user grant it), then reconnect the account."},"reason":{"type":"string","description":"The platform error that revealed it."}}},"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: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"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":"intentional: removed on purpose, for example with DELETE /v1/accounts/{accountId} or by a switch to the Free plan for the accounts over its limit. The account is deleted permanently 1 hour later unless the same account is reconnected within that hour.\n\nunintentional: the connection broke (token expired or revoked, access lost on the platform). The account stays in Zernio, inactive, until it is reconnected (keeping its accountId) or removed."},"reason":{"type":"string","description":"Human-readable reason for the disconnection"}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookAdsSyncAccount":{"type":"object","required":["accountId","profileId","platform","username"],"properties":{"accountId":{"type":"string","description":"The ads connection's account ID (same as used in /v1/accounts/{accountId})"},"profileId":{"type":"string"},"platform":{"type":"string","description":"The ads connection platform, e.g. metaads, googleads, tiktokads, linkedinads"},"username":{"type":"string"},"displayName":{"type":["string","null"]}}},"WebhookAdsSyncAdAccount":{"type":"object","required":["platformAdAccountId","name"],"properties":{"platformAdAccountId":{"type":"string","description":"The platform ad account ID, e.g. act_1489036928764209 on Meta"},"name":{"type":["string","null"]}}},"WebhookPayloadAccountAdsSyncFailed":{"type":"object","description":"Webhook payload for `account.ads.sync_failed` events. Fired once per ad account when its ads stop syncing: no successful sync for 24 hours, or every live ad in it at the retry cap.\n\nIt does not fire again for the same ad account until `account.ads.sync_recovered`. Metrics for the ad account are stale meanwhile.\n","required":["id","event","account","adAccount","sync","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["account.ads.sync_failed"]},"account":{"$ref":"#/components/schemas/WebhookAdsSyncAccount"},"adAccount":{"$ref":"#/components/schemas/WebhookAdsSyncAdAccount"},"sync":{"type":"object","required":["lastSuccessfulSyncAt","failureCount","errorCategory","error"],"properties":{"lastSuccessfulSyncAt":{"type":"string","format":"date-time"},"failureCount":{"type":"integer","description":"Consecutive failed sync attempts on the ad account's ads."},"errorCategory":{"type":"string","enum":["ad_account_not_listed","sync_error","stale"],"description":"ad_account_not_listed = the platform no longer returns the ad account to this\nconnection (access removed, or a platform-side change); sync_error = the platform\nreturned an error, see `error`; stale = no sync succeeded and no error was\nrecorded. New values may be added.\n"},"error":{"type":"string","description":"Human-readable detail, for display and debugging. Branch on errorCategory."}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event. Retries and redeliveries keep the original value."}}},"WebhookPayloadAccountAdsSyncRecovered":{"type":"object","description":"Webhook payload for `account.ads.sync_recovered` events. Fired once when an ad account\npreviously reported by `account.ads.sync_failed` syncs successfully again.\n","required":["id","event","account","adAccount","sync","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["account.ads.sync_recovered"]},"account":{"$ref":"#/components/schemas/WebhookAdsSyncAccount"},"adAccount":{"$ref":"#/components/schemas/WebhookAdsSyncAdAccount"},"sync":{"type":"object","required":["lastSuccessfulSyncAt","failingSince"],"properties":{"lastSuccessfulSyncAt":{"type":"string","format":"date-time"},"failingSince":{"type":"string","format":"date-time","description":"The last successful sync before the failure started."}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event. Retries and redeliveries keep the original value."}}},"WebhookPayloadAccountAdsInitialSyncCompleted":{"type":"object","description":"Webhook payload for `account.ads.initial_sync_completed` events.\nFired once per ads-enabled account when the initial discovery + 90-day\nad backfill finishes (whether it succeeded fully, partially, or failed).\n","required":["id","event","account","sync","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"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\nthat ID back so the webhook can be correlated to the originating connect\nrequest without consulting the consumer's DB. Meta uses the `act_*` shape.\n","example":"act_1330190928038136"},"platformAdAccountIds":{"type":"array","description":"Every ad-account ID that the connected token could see at discovery time.\nUseful for \"we synced ads from these accounts\" UX without a follow-up API call.\nEmpty array when the token had no ad-account visibility.\n","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).\nTruncated to ~2KB. Present when `status` is `failure` (and sometimes on `success`\nwhen discovery saw zero ad accounts). For UX branching prefer `errorCategory`;\nthis field is for human display and debugging.\n"},"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.\n\n- `token_invalid`: access token is expired or revoked. Reconnect.\n- `permission_denied`: token lacks a 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.\n- `no_ad_accounts`: token is valid but sees zero ad accounts. The user needs to connect a Business Manager that owns ad accounts.\n- `rate_limited`: the platform throttled us. Sync retries automatically.\n- `discovery_failed`: any other platform-side failure. Inspect `error`.\n- `unknown`: the classifier could not categorize the failure.\n"}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadCampaignSubmission":{"type":"object","description":"Webhook payload for campaign submission events:\n\n- `campaign_submission.received`: fires for every accepted submission.\n- `campaign_submission.flagged`: fires when a submission gains a flag it did not carry before (at submission or on a later sync). `submission.flags` lists every flag it carries.\n- `campaign_submission.pending_review`: fires when the submission becomes ready for the operator's review.\n- `campaign_submission.approved` and `campaign_submission.rejected`: fire on the operator's decision.\n","required":["id","event","campaign","participant","creator","submission","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["campaign_submission.received","campaign_submission.flagged","campaign_submission.pending_review","campaign_submission.approved","campaign_submission.rejected"]},"campaign":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"participant":{"type":"object","required":["id"],"properties":{"id":{"type":"string"}}},"creator":{"type":"object","required":["id","displayName"],"properties":{"id":{"type":"string"},"displayName":{"type":"string"}}},"submission":{"type":"object","required":["id","platform","platformPostId","platformPostUrl","status","viewsAtSubmission","viewsEligible","engagementsLatest","viewsPaid","flags"],"properties":{"id":{"type":"string"},"platform":{"type":"string","example":"tiktok"},"platformPostId":{"type":"string"},"platformPostUrl":{"type":["string","null"]},"status":{"type":"string","example":"tracking"},"viewsAtSubmission":{"type":["integer","null"]},"viewsEligible":{"type":["integer","null"],"description":"Views that count toward earnings at the latest read."},"engagementsLatest":{"type":["integer","null"],"description":"The campaign engagement types summed at the latest read. An engagements campaign earns on this count."},"viewsPaid":{"type":["integer","null"],"description":"Views from ads, on YouTube and X. Null elsewhere or before the first read."},"flags":{"type":"array","items":{"type":"object","required":["code","detail"],"properties":{"code":{"type":"string","example":"duplicate_post"},"detail":{"type":"string"}}}}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadCreatorCampaign":{"type":"object","description":"Webhook payload for `creator_campaign.budget_exhausted` and `creator_campaign.closed`.\n`budget_exhausted` fires once, when the campaign's earnings first reach\n`campaign.budgetCents`, and carries `campaign.budgetExhaustedAt`. `closed` fires once,\nwhen the campaign closes, and carries `campaign.closedAt`.\n","required":["id","event","campaign","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["creator_campaign.budget_exhausted","creator_campaign.closed"]},"campaign":{"type":"object","required":["id","name","budgetCents"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"budgetCents":{"type":"integer"},"budgetExhaustedAt":{"type":"string","format":"date-time","description":"Present on creator_campaign.budget_exhausted only."},"closedAt":{"type":"string","format":"date-time","description":"Present on creator_campaign.closed only."}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadCampaignPayout":{"type":"object","description":"Webhook payload for `campaign_payout.payable` and `campaign_payout.settled`.\n\n- `payable`: fires when a participant's held earnings mature. `payout.payableCents` is the participant's whole payable balance, so a partner paying from its own rails pays that amount and records it with `POST /v1/creator-campaigns/{campaignId}/participants/{participantId}/settle`.\n- `settled`: fires when a settlement is recorded and carries `payout.settlement`.\n- `failed`: fires when a treasury payout is refused, unconfirmed or reversed. The amount returns to payable (minus anything a rejection claws back) and `payout.failure` says why.\n","required":["id","event","campaign","participant","creator","payout","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["campaign_payout.payable","campaign_payout.settled","campaign_payout.failed"]},"campaign":{"type":"object","required":["id","name","settlement"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"settlement":{"type":"string","enum":["none","external","treasury"]}}},"participant":{"type":"object","required":["id"],"properties":{"id":{"type":"string"}}},"creator":{"type":"object","required":["id","displayName"],"properties":{"id":{"type":"string"},"displayName":{"type":"string"}}},"payout":{"type":"object","required":["payableCents"],"properties":{"payableCents":{"type":"integer","description":"The participant's payable balance after this event."},"settlement":{"type":"object","description":"Present on campaign_payout.settled only.","required":["entryId","amountCents","externalReference","recorded"],"properties":{"entryId":{"type":"string","description":"The ledger settlement entry."},"amountCents":{"type":"integer"},"externalReference":{"type":["string","null"]},"recorded":{"type":"boolean","description":"True when the payout was made outside Zernio and only recorded here; false when Zernio moved the money through the treasury."},"transferId":{"type":"string","description":"Treasury settlement only: the Zernio transfer that moved the money. The creator receives amountCents in full."},"feeCents":{"type":"integer","description":"Treasury settlement only: the transfer fee, added on top of amountCents."},"totalCents":{"type":"integer","description":"Treasury settlement only: debited from your balance, amountCents plus feeCents."}}},"failure":{"type":"object","description":"Present on campaign_payout.failed only.","required":["transferId","amountCents","reason"],"properties":{"transferId":{"type":"string","description":"The Zernio transfer that did not go through."},"amountCents":{"type":"integer","description":"The payout amount that did not reach the creator. It is returned to payable, minus any amount a rejection made while the payout was in flight claws back to the campaign budget; payableCents is the balance after both."},"reason":{"type":"string","enum":["returned","stale","reversed"],"description":"returned: Stripe refused the transfer. stale: it could not be confirmed with Stripe within 24 hours. reversed: Stripe reversed it after it was sent; the settlement is undone."}}}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadCampaignParticipant":{"type":"object","description":"Webhook payload for `campaign_participant.joined`, `campaign_participant.suspended` and\n`campaign_participant.removed`. `participant.status` is the status after the change.\n`participant.joinedAt` is null for a participant removed before they ever joined.\n","required":["id","event","campaign","participant","creator","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["campaign_participant.joined","campaign_participant.suspended","campaign_participant.removed"]},"campaign":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"participant":{"type":"object","required":["id","status","joinedAt"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["invited","active","suspended","removed"]},"joinedAt":{"type":["string","null"],"format":"date-time"}}},"creator":{"type":"object","required":["id","displayName"],"properties":{"id":{"type":"string"},"displayName":{"type":"string"}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"CreatorCampaignEconomics":{"description":"How the campaign pays, picked by `type`. Amounts are USD cents.\n\nEvery type carries `budgetCents`, the most the campaign can pay out in total. Once earnings reach it, the campaign stops accruing and `creator_campaign.budget_exhausted` fires.\n\n- `cpm`: `ratePer1kCents` per 1,000 of the counted `metric` (views by default), earned once a post reaches `minViewsToEarn` of it, capped per post by `maxPayoutPerClipCents`.\n- `per_post`: `perApprovedPostCents` for each approved post, at most `maxPostsPerParticipant` per participant.\n- `pool`: `budgetCents` is split at close among approved posts by eligible views; a post needs `minViewsToQualify` views to share.\n","oneOf":[{"$ref":"#/components/schemas/CreatorCampaignEconomicsCpm"},{"$ref":"#/components/schemas/CreatorCampaignEconomicsPerPost"},{"$ref":"#/components/schemas/CreatorCampaignEconomicsPool"}],"discriminator":{"propertyName":"type","mapping":{"cpm":"#/components/schemas/CreatorCampaignEconomicsCpm","per_post":"#/components/schemas/CreatorCampaignEconomicsPerPost","pool":"#/components/schemas/CreatorCampaignEconomicsPool"}}},"CreatorCampaignEconomicsCpm":{"type":"object","title":"CPM","required":["type","ratePer1kCents","minViewsToEarn","budgetCents"],"properties":{"type":{"type":"string","enum":["cpm"]},"metric":{"type":"string","enum":["views","engagements"],"default":"views","description":"What the rate pays on. `engagements` counts the `engagementTypes` as each platform reports them, and `minViewsToEarn` then applies to engagements. Fixed once the campaign leaves draft."},"engagementTypes":{"type":"array","minItems":1,"items":{"type":"string","enum":["likes","comments","shares","saves"]},"description":"With `metric: engagements`, the engagements that count. Missing means all four, and sending it on a views campaign answers 400. YouTube reports likes and comments only, Facebook and Threads have no saves, and Pinterest reports saves only."},"organicViewsOnly":{"type":"boolean","default":false,"description":"Count only organic views: views from ads the creator ran do not earn. Every campaign platform must be YouTube or X, which report ad views per post, or the request answers 400. A post earns nothing until its ad views were first read."},"ratePer1kCents":{"type":"integer","minimum":1},"minViewsToEarn":{"type":"integer","minimum":0,"description":"The count a post must reach before it earns, in the campaign metric (views or engagements)."},"maxPayoutPerClipCents":{"type":"integer","minimum":1},"budgetCents":{"type":"integer","minimum":0}}},"CreatorCampaignEconomicsPerPost":{"type":"object","title":"Per post","required":["type","perApprovedPostCents","budgetCents"],"properties":{"type":{"type":"string","enum":["per_post"]},"perApprovedPostCents":{"type":"integer","minimum":1},"maxPostsPerParticipant":{"type":"integer","minimum":1},"budgetCents":{"type":"integer","minimum":0}}},"CreatorCampaignEconomicsPool":{"type":"object","title":"Pool","required":["type","budgetCents","minViewsToQualify"],"properties":{"type":{"type":"string","enum":["pool"]},"budgetCents":{"type":"integer","minimum":0},"minViewsToQualify":{"type":"integer","minimum":0},"organicViewsOnly":{"type":"boolean","default":false,"description":"Count only organic views: views from ads the creator ran do not earn. Every campaign platform must be YouTube or X, which report ad views per post, or the request answers 400. A post earns nothing until its ad views were first read."}}},"CreatorCampaignCaps":{"type":"object","required":["authenticityThreshold"],"properties":{"maxParticipants":{"type":"integer","minimum":1,"description":"Invites and joins past this count answer 403."},"maxSubmissionsPerParticipantPerDay":{"type":"integer","minimum":1,"description":"Posts one participant can submit to this campaign per UTC day, counting every submission whatever its status. The next submit that day answers 409 invalid_resource_state."},"maxAccountsPerParticipant":{"type":"integer","minimum":1,"description":"Accounts a participant can use in this campaign. Connecting a new account past it answers 400; only the first accounts connected, up to this count, can submit posts."},"maxXReadSpendCents":{"type":"integer","minimum":1,"description":"X campaigns only: what tracking X posts may cost in X reads, in cents. Unset means 5000 ($50).\n\nX bills one read per tracked post per UTC day, and you pay it at cost through usage-based billing.\n\nWhen it is spent, open X posts stop counting views and are flagged `x_read_cap`, and new X posts answer 409.\n"},"authenticityThreshold":{"type":"number","minimum":0,"maximum":100,"description":"A submission whose authenticity score falls below this is flagged `low_authenticity`. It is never rejected automatically. Defaults to 40 on create."}}},"CreatorCampaignBranding":{"type":"object","description":"Branding of the hosted join page, in the connect-link branding shape.","properties":{"brandName":{"type":"string"},"primaryColor":{"type":"string"},"logoUrl":{"type":"string"},"theme":{"type":"object","additionalProperties":true}}},"CampaignSubmissionCounts":{"type":"object","description":"Number of submissions in each status.","required":["received","tracking","pending_review","approved","rejected","expired","withdrawn"],"properties":{"received":{"type":"integer"},"tracking":{"type":"integer"},"pending_review":{"type":"integer"},"approved":{"type":"integer"},"rejected":{"type":"integer"},"expired":{"type":"integer"},"withdrawn":{"type":"integer"}}},"CreatorCampaign":{"type":"object","required":["id","userId","profileId","kind","name","brandName","status","type","currency","platforms","contentRules","startsAt","endsAt","trackingDays","holdDays","maxPostAgeMinutes","settlement","economics","caps","branding","budgetExhaustedAt","closedAt","activatedAt","payableScannedAt","createdAt","updatedAt","hasOpenInvite","consumedCents","participantCount","submissionCounts","payableCents"],"properties":{"id":{"type":"string"},"userId":{"type":"string","description":"The workspace billing owner the campaign belongs to."},"profileId":{"type":"string","description":"The profile that scopes the campaign: API keys, teammates and webhooks scoped to it reach the campaign."},"kind":{"type":"string","example":"clipping"},"name":{"type":"string"},"brandName":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","closed"],"description":"draft until activated; active accepts submissions and accrues; paused stops new submissions; closed is final."},"type":{"type":"string","enum":["cpm","per_post","pool"],"description":"Same as economics.type."},"currency":{"type":"string","example":"usd"},"platforms":{"type":"array","items":{"type":"string","enum":["tiktok","instagram","youtube","threads","pinterest","facebook","twitter"]}},"contentRules":{"type":["string","null"],"description":"Free-text rules shown to creators on the join page."},"startsAt":{"type":["string","null"],"format":"date-time"},"endsAt":{"type":["string","null"],"format":"date-time","description":"No new submissions after this time; the campaign closes once every tracking window had its final read."},"trackingDays":{"type":"integer","description":"How long each submitted post is tracked."},"holdDays":{"type":"integer","description":"Days approved earnings are held before they become payable."},"maxPostAgeMinutes":{"type":["integer","null"],"description":"A post older than this many minutes when submitted is refused. Null (the default) accepts any age. Either way, a post published before the campaign started (`startsAt`, or `activatedAt` without one) is refused."},"activatedAt":{"type":["string","null"],"format":"date-time","description":"When the campaign was first activated. Without `startsAt`, posts must be published after this moment."},"settlement":{"type":"string","enum":["none","external","treasury"],"description":"none: settle records a payout made elsewhere. external: you pay from your own rails on campaign_payout.payable and settle with your reference. treasury: settle moves the money from your Zernio balance to the creator's Stripe account, and the creator sets up payouts from their campaign page."},"economics":{"$ref":"#/components/schemas/CreatorCampaignEconomics"},"caps":{"$ref":"#/components/schemas/CreatorCampaignCaps"},"branding":{"oneOf":[{"$ref":"#/components/schemas/CreatorCampaignBranding"},{"type":"null"}]},"budgetExhaustedAt":{"type":["string","null"],"format":"date-time"},"closedAt":{"type":["string","null"],"format":"date-time"},"payableScannedAt":{"type":["string","null"],"format":"date-time","description":"Internal watermark of the payable scan."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"hasOpenInvite":{"type":"boolean","description":"True once an open invite link was created. The link itself is returned only when it is created."},"consumedCents":{"type":"integer","description":"Budget used so far: earnings accrued, approved or adjusted against the campaign."},"participantCount":{"type":"integer"},"submissionCounts":{"$ref":"#/components/schemas/CampaignSubmissionCounts"},"payableCents":{"type":"integer","description":"What the campaign's creators can be paid now, summed over every participant's payable balance."}}},"CreateCreatorCampaignRequest":{"type":"object","required":["profileId","name","brandName","economics"],"properties":{"profileId":{"type":"string","description":"Profile the campaign lives in. Creator accounts connect into the same workspace."},"name":{"type":"string","minLength":1,"maxLength":200},"brandName":{"type":"string","minLength":1,"maxLength":200},"economics":{"$ref":"#/components/schemas/CreatorCampaignEconomics"},"caps":{"allOf":[{"$ref":"#/components/schemas/CreatorCampaignCaps"}],"description":"Omitted, the campaign starts with authenticityThreshold 40 and no other caps."},"platforms":{"type":"array","items":{"type":"string","enum":["tiktok","instagram","youtube","threads","pinterest","facebook","twitter"]},"description":"Platforms creators may post on. At least one is needed to activate. `twitter` (X) needs usage-based billing: X reads are billed at cost, up to `caps.maxXReadSpendCents`, and X views are the post's impressions. `facebook` takes Page reels and videos only."},"contentRules":{"type":["string","null"],"maxLength":10000},"startsAt":{"type":["string","null"],"format":"date-time"},"endsAt":{"type":["string","null"],"format":"date-time"},"trackingDays":{"type":"integer","minimum":1,"maximum":365,"default":30},"holdDays":{"type":"integer","minimum":0,"maximum":90,"default":10},"maxPostAgeMinutes":{"type":["integer","null"],"minimum":1,"description":"Optional maximum age in minutes of a post when it is submitted. Null or omitted (the default) accepts any age. Posts published before the campaign started are always refused."},"settlement":{"type":"string","enum":["none","external","treasury"],"default":"none"},"branding":{"oneOf":[{"$ref":"#/components/schemas/CreatorCampaignBranding"},{"type":"null"}]}}},"UpdateCreatorCampaignRequest":{"type":"object","minProperties":1,"description":"Every field is optional; send at least one. `economics` can only change while the campaign is a draft.","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"brandName":{"type":"string","minLength":1,"maxLength":200},"platforms":{"type":"array","items":{"type":"string","enum":["tiktok","instagram","youtube","threads","pinterest","facebook","twitter"]}},"contentRules":{"type":["string","null"],"maxLength":10000},"startsAt":{"type":["string","null"],"format":"date-time"},"endsAt":{"type":["string","null"],"format":"date-time"},"trackingDays":{"type":"integer","minimum":1,"maximum":365},"holdDays":{"type":"integer","minimum":0,"maximum":90},"maxPostAgeMinutes":{"type":["integer","null"],"minimum":1,"description":"Null removes the limit."},"settlement":{"type":"string","enum":["none","external","treasury"]},"economics":{"$ref":"#/components/schemas/CreatorCampaignEconomics"},"caps":{"$ref":"#/components/schemas/CreatorCampaignCaps"},"branding":{"oneOf":[{"$ref":"#/components/schemas/CreatorCampaignBranding"},{"type":"null"}]}}},"CampaignParticipantBalances":{"type":"object","description":"USD cents in each state. accruing: earned on posts not yet approved. owed: approved and on hold. payable: past the hold, ready to pay. settling: a treasury payout in progress, no longer payable and not reversible by a reject. settled: paid out.","required":["accruing","owed","payable","settling","settled"],"properties":{"accruing":{"type":"integer"},"owed":{"type":"integer"},"payable":{"type":"integer"},"settling":{"type":"integer"},"settled":{"type":"integer"}}},"CampaignParticipant":{"type":"object","required":["id","campaignId","creator","status","joinedAt","accounts","balances","flags","submissionCounts","payout"],"properties":{"id":{"type":"string"},"campaignId":{"type":"string"},"creator":{"type":"object","required":["id","displayName","email"],"properties":{"id":{"type":"string"},"displayName":{"type":"string"},"email":{"type":["string","null"]}}},"status":{"type":"string","enum":["invited","active","suspended","removed"]},"joinedAt":{"type":["string","null"],"format":"date-time"},"accounts":{"type":"array","description":"Social accounts the creator connected, verified once Zernio confirmed the creator owns them.","items":{"type":"object","required":["accountId","verifiedAt","platform","username"],"properties":{"accountId":{"type":"string"},"verifiedAt":{"type":["string","null"],"format":"date-time"},"platform":{"type":["string","null"],"description":"Null when the account is no longer active on the creator profile."},"username":{"type":["string","null"],"description":"The handle on the platform; null when the account is no longer active."}}}},"balances":{"$ref":"#/components/schemas/CampaignParticipantBalances"},"flags":{"type":"array","items":{"type":"object","required":["code","detail","raisedAt"],"properties":{"code":{"type":"string","enum":["linked_accounts","cross_operator"]},"detail":{"type":"string"},"raisedAt":{"type":"string","format":"date-time"}}}},"submissionCounts":{"$ref":"#/components/schemas/CampaignSubmissionCounts"},"payout":{"type":"object","description":"How far the creator got with Stripe payout setup. Only `ready` creators can be paid through the Zernio treasury.","required":["status"],"properties":{"status":{"type":"string","enum":["not_started","onboarding","ready","restricted"],"description":"`not_started`: no payout account yet. `onboarding`: setup started or under review. `ready`: payouts enabled. `restricted`: Stripe needs more information before paying out."}}}}},"CampaignSubmissionFlag":{"type":"object","required":["code","detail","raisedAt"],"properties":{"code":{"type":"string","enum":["duplicate_media","duplicate_post","view_spike","linked_accounts","cross_operator","unreachable","post_deleted","account_restricted","low_authenticity","x_read_cap","paid_views","organic_unverified"]},"detail":{"type":"string"},"raisedAt":{"type":"string","format":"date-time"}}},"CampaignSubmission":{"type":"object","required":["id","campaignId","participantId","creatorId","accountId","platform","platformPostId","platformPostUrl","externalPostId","trackingWindowId","mediaHash","submittedAt","postPublishedAt","status","rejectReason","reviewRound","reviewedBy","reviewedAt","viewsAtSubmission","viewsLatest","viewsEligible","engagementsLatest","viewsPaid","paidViewsReadAt","lastAccruedViews","accruedCents","approvedCents","authenticityScore","authenticityConfidence","flags","createdAt","updatedAt","creator","authenticity","earnedCents","releasedCents","paidOutCents","window","post"],"properties":{"id":{"type":"string"},"campaignId":{"type":"string"},"participantId":{"type":"string"},"creatorId":{"type":"string"},"accountId":{"type":"string","description":"The creator account the post was published from."},"platform":{"type":"string","enum":["tiktok","instagram","youtube","threads","pinterest","facebook","twitter"]},"platformPostId":{"type":"string"},"platformPostUrl":{"type":["string","null"]},"externalPostId":{"type":["string","null"],"description":"The tracked external post (see /v1/external-posts)."},"trackingWindowId":{"type":["string","null"]},"mediaHash":{"type":["string","null"]},"submittedAt":{"type":"string","format":"date-time"},"postPublishedAt":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","enum":["received","tracking","pending_review","approved","rejected","expired","withdrawn"]},"rejectReason":{"type":["string","null"]},"reviewRound":{"type":"integer","minimum":0,"description":"How many times the post was reopened after a reject. 0 until the first reopen."},"reviewedBy":{"type":["string","null"],"description":"User id of the reviewer."},"reviewedAt":{"type":["string","null"],"format":"date-time"},"viewsAtSubmission":{"type":["integer","null"],"description":"Views when the post was submitted. They count toward earnings like every later view."},"viewsLatest":{"type":["integer","null"],"description":"Latest view count read for the post, frozen at the tracking window end."},"viewsEligible":{"type":["integer","null"],"description":"Views that count toward earnings: every view the platform reports for the post, including those before submission, read at the tracking window end at the latest: once the window completes or is cancelled, the last read at or before its end is final and this value stops moving."},"engagementsLatest":{"type":["integer","null"],"description":"The campaign engagement types summed at the latest read (all four on a views campaign), frozen at the tracking window end like `viewsEligible`. An `engagements` campaign earns on this count."},"viewsPaid":{"type":["integer","null"],"description":"Views from ads the creator ran: YouTube views from the advertising traffic source, X impressions beyond the organic ones. Null on other platforms and before the first read. On an organic-only campaign `viewsEligible` is the latest views minus these."},"paidViewsReadAt":{"type":["string","null"],"format":"date-time","description":"When `viewsPaid` was last read. YouTube refreshes every 6 hours and reports ad views up to 2 days late; X about once a day while the post is under 30 days old."},"lastAccruedViews":{"type":"integer"},"accruedCents":{"type":"integer"},"approvedCents":{"type":"integer"},"authenticityScore":{"type":["integer","null"],"minimum":0,"maximum":100},"authenticityConfidence":{"type":["number","null"]},"flags":{"type":"array","items":{"$ref":"#/components/schemas/CampaignSubmissionFlag"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"creator":{"type":"object","required":["id","displayName"],"properties":{"id":{"type":"string"},"displayName":{"type":"string"}}},"authenticity":{"type":["object","null"],"description":"0 to 100, where 100 means the view pattern looks organic. Null until the post is scored.","required":["score","confidence","reasons"],"properties":{"score":{"type":"integer"},"confidence":{"type":["number","null"]},"reasons":{"type":"array","items":{}}}},"earnedCents":{"type":"integer","description":"approvedCents once approved, otherwise accruedCents."},"releasedCents":{"type":"integer","description":"Approved cents whose hold is over, so payable or already paid out. 0 unless approved."},"paidOutCents":{"type":"integer","description":"What rejecting this post could not take back now: releasedCents beyond the creator's payable balance. It stays paid; the dashboard warns before such a reject."},"window":{"type":["object","null"],"description":"The tracking window that samples the post.","required":["id","endsAt","status"],"properties":{"id":{"type":"string"},"endsAt":{"type":"string","format":"date-time"},"status":{"type":"string"}}},"post":{"type":"object","description":"The post itself, as the review drawer shows it. Thumbnail and caption are null until the post has been synced.","required":["thumbnailUrl","caption","accountHandle","publishedAt"],"properties":{"thumbnailUrl":{"type":["string","null"]},"caption":{"type":["string","null"]},"accountHandle":{"type":["string","null"],"description":"The @handle of the connected account that published the post, without the @."},"publishedAt":{"type":"string","format":"date-time","description":"When the post went live; the submission time if that is not known."}}}}},"CampaignSubmissionDetail":{"allOf":[{"$ref":"#/components/schemas/CampaignSubmission"},{"type":"object","required":["samples"],"properties":{"samples":{"type":"array","description":"Counters per sync, newest first, up to 500.","items":{"type":"object","required":["syncedAt","views","likes","comments","shares","saves"],"properties":{"syncedAt":{"type":"string","format":"date-time"},"views":{"type":"integer"},"likes":{"type":"integer"},"comments":{"type":"integer"},"shares":{"type":"integer"},"saves":{"type":"integer"}}}}}}]},"CampaignLedgerEntry":{"type":"object","required":["id","kind","amountCents","debit","credit","holdUntil","releasedByEntryId","reversesEntryId","referenceType","referenceId","cause","externalReference","actor","createdAt"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["accrual","approval","hold_release","adjustment","settling","settlement","reversal","topup","transfer","fee","usage","grant"]},"amountCents":{"type":"integer","description":"Always positive; direction is given by debit and credit."},"debit":{"$ref":"#/components/schemas/LedgerAccountSide"},"credit":{"$ref":"#/components/schemas/LedgerAccountSide"},"holdUntil":{"type":["string","null"],"format":"date-time"},"releasedByEntryId":{"type":["string","null"]},"reversesEntryId":{"type":["string","null"]},"referenceType":{"type":["string","null"]},"referenceId":{"type":["string","null"]},"cause":{"type":"string"},"externalReference":{"type":["string","null"],"description":"The payout reference recorded with a settlement (your transfer or invoice id)."},"actor":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"CampaignPayable":{"type":"object","required":["participantId","creator","payableCents","entries"],"properties":{"participantId":{"type":"string"},"creator":{"type":"object","required":["id","displayName"],"properties":{"id":{"type":"string"},"displayName":{"type":"string"}}},"payableCents":{"type":"integer","description":"The participant's whole payable balance."},"entries":{"type":"array","items":{"type":"string"},"description":"Ids of the newest ledger entries into payable that add up to the balance (up to 200)."}}},"CampaignSettlement":{"type":"object","required":["entryId","participantId","amountCents","externalReference","payableCents","settledAt"],"properties":{"entryId":{"type":"string","description":"The ledger settlement entry."},"participantId":{"type":"string"},"amountCents":{"type":"integer"},"externalReference":{"type":["string","null"]},"payableCents":{"type":"integer","description":"Payable balance left after this settlement."},"settledAt":{"type":"string","format":"date-time"},"transferId":{"type":"string","description":"Treasury settlement only: the Zernio transfer that moved the money. The creator receives amountCents in full."},"feeCents":{"type":"integer","description":"Treasury settlement only: the transfer fee, added on top of amountCents."},"totalCents":{"type":"integer","description":"Treasury settlement only: debited from your balance, amountCents plus feeCents."}}},"CampaignAdjustment":{"type":"object","required":["id","kind","participantId","amountCents","cause","actor","createdAt"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["adjustment"]},"participantId":{"type":"string"},"amountCents":{"type":"integer","description":"Positive credits the participant, negative claws back."},"cause":{"type":"string"},"actor":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"CampaignReport":{"type":"object","required":["spend","views","engagements","submissions","participants","authenticity"],"properties":{"spend":{"type":"object","required":["budgetCents","consumedCents","settledCents"],"properties":{"budgetCents":{"type":"integer"},"consumedCents":{"type":"integer"},"settledCents":{"type":"integer"}}},"views":{"type":"object","description":"Summed over submissions that are not rejected or withdrawn.","required":["eligible","total","paid"],"properties":{"eligible":{"type":"integer","description":"Views that count toward earnings."},"total":{"type":"integer","description":"Latest view counts."},"paid":{"type":"integer","description":"Views from ads, on YouTube and X posts."}}},"engagements":{"type":"integer","description":"The campaign engagement types summed over the same submissions."},"submissions":{"$ref":"#/components/schemas/CampaignSubmissionCounts"},"participants":{"type":"array","description":"Top 10 participants by payable, settling and settled cents.","items":{"type":"object","required":["participantId","creator","payableCents","settlingCents","settledCents"],"properties":{"participantId":{"type":"string"},"creator":{"type":"object","required":["id","displayName"],"properties":{"id":{"type":"string"},"displayName":{"type":"string"}}},"payableCents":{"type":"integer"},"settlingCents":{"type":"integer","description":"A treasury payout in progress."},"settledCents":{"type":"integer"}}}},"authenticity":{"type":"array","description":"Authenticity score histogram in ten buckets (0-9 through 90-100).","items":{"type":"object","required":["from","to","count"],"properties":{"from":{"type":"integer"},"to":{"type":"integer"},"count":{"type":"integer"}}}}}},"TrackingWindow":{"type":"object","required":["id","postId","accountId","platform","platformPostId","startsAt","endsAt","status","finalReadAt","completionReason","requestedBy","latest"],"properties":{"id":{"type":"string"},"postId":{"type":"string","description":"The external post being tracked"},"accountId":{"type":"string"},"platform":{"type":"string","example":"tiktok"},"platformPostId":{"type":"string","description":"The post's id on the platform"},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["open","completing","completed","cancelled"]},"finalReadAt":{"type":["string","null"],"format":"date-time","description":"When the closing read ran. Null until then."},"completionReason":{"type":["string","null"],"enum":["final_read","unreachable","post_deleted","cancelled",null],"description":"How the window closed. Null while it is open."},"requestedBy":{"type":"string"},"latest":{"type":["object","null"],"description":"The latest verified numbers we read from the platform. Null when no sample exists yet.","required":["views","likes","comments","shares","saves","syncedAt"],"properties":{"views":{"type":"integer"},"likes":{"type":"integer"},"comments":{"type":"integer"},"shares":{"type":"integer"},"saves":{"type":"integer"},"syncedAt":{"type":["string","null"],"format":"date-time"}}}}},"TrackingWindowResponse":{"type":"object","required":["window"],"properties":{"window":{"$ref":"#/components/schemas/TrackingWindow"}}},"PostSample":{"type":"object","required":["syncedAt","views","likes","comments","shares","saves","watchSeconds","completionRate"],"properties":{"syncedAt":{"type":"string","format":"date-time","description":"When Zernio fetched this reading from the platform"},"views":{"type":"integer"},"likes":{"type":"integer"},"comments":{"type":"integer"},"shares":{"type":["integer","null"],"description":"Null on platforms that do not return shares"},"saves":{"type":["integer","null"],"description":"Null on platforms that do not return saves"},"watchSeconds":{"type":["number","null"],"description":"Average watch time in seconds. Null when the platform gives none."},"completionRate":{"type":["number","null"],"description":"Share of viewers who watched to the end, 0 to 1. Null when the platform gives none."}}},"PostAuthenticity":{"type":"object","required":["postId","score","confidence","reasons","version","computedAt","sampleCount"],"properties":{"postId":{"type":"string","description":"The external post the score belongs to"},"score":{"type":"integer","minimum":0,"maximum":100,"description":"Higher means the view pattern looks more organic"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"How much data the score rests on"},"reasons":{"type":"array","description":"Each factor that lowered the score, with its weight in points","items":{"type":"object","required":["code","weight"],"properties":{"code":{"type":"string","enum":["late_block","flat_engagement","view_follower_gap","cap_seeking","prior_flags","no_watch_signal"]},"weight":{"type":"number","description":"Points taken off 100. Zero for no_watch_signal, which only lowers confidence."}}}},"version":{"type":"string","description":"Scoring model version"},"computedAt":{"type":"string","format":"date-time"},"sampleCount":{"type":"integer","description":"Number of samples the score was computed from"}}},"WebhookPayloadPostTrackingCompleted":{"type":"object","description":"Webhook payload for `post.tracking_completed`. Fired once when a post's tracking window ends and its final analytics read has run.\n\n`final` holds the closing metrics, or null when no sample could be read.\n\n`window.completionReason` says how the window closed:\n\n- `final_read`: the read succeeded.\n- `unreachable`: the sync failed or no sample exists.\n- `post_deleted`: the post is gone from the platform; `final` is then the last sample we held, if any.\n","required":["id","event","post","window","final","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["post.tracking_completed"]},"post":{"type":"object","required":["id","platform","platformPostId","accountId","profileId"],"properties":{"id":{"type":"string","description":"Zernio's id for the tracked post"},"platform":{"type":"string","example":"instagram"},"platformPostId":{"type":"string","description":"The post's id on the platform"},"accountId":{"type":"string","description":"The connected account the post belongs to"},"profileId":{"type":"string","description":"The profile that account belongs to"}}},"window":{"type":"object","required":["id","startsAt","endsAt","finalReadAt","completionReason"],"properties":{"id":{"type":"string"},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"finalReadAt":{"type":"string","format":"date-time"},"completionReason":{"type":"string","enum":["final_read","unreachable","post_deleted"]}}},"final":{"type":["object","null"],"description":"The closing metrics, or null when none could be read.","required":["views","likes","comments","shares","saves","syncedAt"],"properties":{"views":{"type":"integer"},"likes":{"type":"integer"},"comments":{"type":"integer"},"shares":{"type":"integer"},"saves":{"type":"integer"},"syncedAt":{"type":"string","format":"date-time"}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadPostAuthenticityChanged":{"type":"object","description":"Webhook payload for `post.authenticity_changed`. Fired when a tracked post's\nauthenticity score crosses 40 in either direction while its window is open.\nA post's first score never fires it.\n","required":["id","event","post","authenticity","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["post.authenticity_changed"]},"post":{"type":"object","required":["id","platform","platformPostId","accountId","profileId"],"properties":{"id":{"type":"string","description":"Zernio's id for the tracked post"},"platform":{"type":"string","example":"instagram"},"platformPostId":{"type":"string","description":"The post's id on the platform"},"accountId":{"type":"string","description":"The connected account the post belongs to"},"profileId":{"type":"string","description":"The profile that account belongs to"}}},"authenticity":{"type":"object","required":["score","previousScore","confidence","reasons","version","computedAt"],"properties":{"score":{"type":"integer","description":"0 to 100, higher is more authentic"},"previousScore":{"type":"integer"},"confidence":{"type":"number","description":"0 to 1, how much data the score rests on"},"reasons":{"type":"array","items":{"type":"object","required":["code","weight"],"properties":{"code":{"type":"string"},"weight":{"type":"number"}}}},"version":{"type":"string","description":"Scoring model version"},"computedAt":{"type":"string","format":"date-time"}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadAnalyticsSynced":{"type":"object","description":"Webhook payload for `analytics.synced`. Fired once per connected account each time its analytics sync cycle completes successfully. Poll-driven (roughly hourly per account), not real-time, and never fired for a skipped or failed cycle.\n\nA TRIGGER, not a transport: it deliberately carries no metrics and no cursor. When it arrives, call `GET /v1/analytics/delta` with YOUR OWN last `nextCursor` to read what changed, across every account, in one paginated stream.\n\n**Why there is no cursor.** The feed's ordering position is assigned inside the analytics store when the row is materialized, which normally happens after this event fires. A cursor minted here could sit ahead of the rows the event announces and make you skip them. Your own `nextCursor` never can.\n\nBecause of the same lag, a delta read issued the instant this event lands can legitimately come back empty. That is not \"nothing changed\": poll again with the same cursor you last used rather than treating the account as done.\n\n**Use a DEDICATED webhook endpoint.** This event is high volume (roughly one delivery per connected account per hour), and a subscription's consecutive-failure count is shared across all its events. An outage while it flows can suppress the low-volume publishing events on the same subscription.\n","required":["id","event","account","sync","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["analytics.synced"]},"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 this account belongs to"},"platform":{"type":"string","example":"youtube"},"username":{"type":"string"}}},"sync":{"type":"object","description":"Summary of the analytics sync cycle that completed.","required":["syncedAt","postsUpdated"],"properties":{"syncedAt":{"type":"string","format":"date-time","description":"When the cycle COMPLETED. Not a join key for the delta feed: the rows a\ncycle produces carry a `syncedAt` stamped when the cycle STARTED, which\nis measured at around one second earlier at the median and up to a\ncouple of minutes earlier in the tail. Correlate on `account.accountId`.\n"},"postsUpdated":{"type":"integer","description":"Post records created or modified by this cycle. Not the number of delta\nfeed rows the cycle produced, which the syncer does not report, so a\ncycle with a non-zero `postsUpdated` can still yield an empty delta page.\n","example":42}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued)."}}},"WebhookPayloadComment":{"type":"object","description":"Webhook payload for comment received events (Instagram, Facebook, Threads, YouTube, LinkedIn, Bluesky, Reddit, TikTok). X/Twitter does NOT fire this event. TikTok events carry only the author id: the comment.update webhook has no username, picture or owner flag.","required":["id","event","comment","post","account","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"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","threads","youtube","linkedin","bluesky","reddit","tiktok"]},"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"]},"isOwnAccount":{"type":"boolean","description":"True when this comment was authored by the connected account itself. Absent means not evaluated, never \"not the account\".\n\n- Instagram and Facebook realtime webhooks: populated (Meta re-delivers the account's own replies as comments events).\n- TikTok: inferred. Comments created through this API are always flagged, and once the account's own author identifier is known (from one of those or from a comments listing), every author is compared against it.\n"},"instagramProfile":{"type":"object","description":"Instagram only, best-effort. Present ONLY for commenters who have\nmessaged the account before: Meta gates the follow relationship behind\nmessaging consent, and commenting does not grant it. Absent otherwise -\ntreat a missing object as \"unknown\", never as \"not a follower\". To check\non demand, call GET /v1/accounts/{accountId}/follow-status/{userId}.\n","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"},"isLive":{"type":"boolean","description":"Instagram only: true when the comment was made on a live broadcast (the live_comments webhook field). Absent on every other comment."},"ad":{"type":"object","description":"Ad context. Present only when the comment was made on paid content; absent for comments on organic posts that are not promoted.\n\n**Instagram**: populated from the webhook payload's value.media.ad_id, value.media.ad_title and value.media.original_media_id, each only when Meta includes it.\n\n**Facebook**: populated from a Graph API lookup of the parent post. Present when the post is an ad dark post (isDarkPost true, whatever its promotionStatus) or an organic post that is or was boosted (promotionStatus \"active\", \"extendable\" or \"finished\").\n\nMeta does not link a dark post to its ad, so on Facebook id is set only when a Meta Ads account is connected and exactly one of its ads has the same text as the post. title is never set on Facebook.\n","properties":{"id":{"type":"string","description":"Meta ad ID. Instagram: from the webhook. Facebook: only when a connected Meta Ads account has one ad with the same text."},"title":{"type":"string","description":"Ad creative title (Instagram only)."},"originalMediaId":{"type":"string","description":"Original media ID that Meta reports for the ad (Instagram only)."},"promotionStatus":{"type":"string","description":"Facebook only. The parent post's promotion_status as the Graph API returns it, for example\n\"active\" (organic post currently boosted). Ad dark posts usually report \"inactive\" and\nsometimes \"ineligible\", so use isDarkPost, not this value, to tell an ad comment apart.\n"},"isDarkPost":{"type":"boolean","description":"Facebook only: true when the post is an unpublished ad creative (dark post), false for a boosted organic post."}}},"attachment":{"allOf":[{"$ref":"#/components/schemas/CommentAttachment"}],"description":"Facebook only. Present on graphic-only comments (sticker, GIF, photo) that carry no text:\nthe webhook only includes it when the comment has no text. The REST comments API returns it\nwhenever Facebook returns one, text or not.\n"}}},"post":{"type":"object","required":["id","platformPostId","content","imageUrl","permalink"],"properties":{"id":{"type":["string","null"],"description":"Internal post ID (null for posts not published through Zernio)"},"platformPostId":{"type":"string","description":"Platform's post ID"},"content":{"type":["string","null"],"description":"Post text, from our synced copy. No platform call is made on the comment path, so null when the post was never synced."},"imageUrl":{"type":["string","null"],"description":"Post thumbnail or first media item URL. Platform CDN URLs expire, fetch promptly."},"permalink":{"type":["string","null"],"description":"Public URL of the post. Null when no URL was ever stored for it, for example a platform draft or a post recovered without one."}}},"account":{"type":"object","required":["id","platform","username"],"properties":{"id":{"type":"string","description":"Account ID"},"accountId":{"type":"string","description":"Account ID (same as id); canonical field for account filtering."},"platform":{"type":"string"},"username":{"type":"string"}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"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: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"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.\n"},"consents":{"allOf":[{"$ref":"#/components/schemas/AdLeadConsents"}],"description":"Sent on every delivery since 2026-10-25. Absent when an older event is redelivered, since redeliveries replay the stored payload."},"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","profileId"],"properties":{"id":{"type":"string","description":"Account ID (the facebook account owning the Page)"},"accountId":{"type":"string","description":"Account ID (same as id); canonical field for account filtering."},"platform":{"type":"string","enum":["facebook"]},"profileId":{"type":["string","null"],"description":"Profile ID of the account that received the lead. Null when the lead has no profile on record."}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"ReviewWebhookReview":{"type":"object","description":"Review data shared by review.new, review.updated and review.restored 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 Profile)."},"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 Profile 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: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"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":"Account ID (same as id); canonical field for account filtering."},"platform":{"type":"string"},"username":{"type":"string"}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadReviewUpdated":{"type":"object","description":"Webhook payload for the review.updated event. Same shape as review.new.\n\nFired when the reviewer edits their text or rating, or when a reply is added, edited or removed.\n\nA reply posted through POST /v1/inbox/reviews/{reviewId}/reply fires immediately. The periodic check then reports it again with the full review payload, so expect a second delivery.\n\n\nReplies written or removed in Google's own interface, and replies removed through the API, are reported by the periodic check.\n\n\nFor replies written in Google, that is usually within 6 hours for reviews updated in the last 30 days, and usually within about 7 days for older ones.\n\n\nOnly teams with a webhook subscribed to review.updated are checked. A removed reply fires with hasReply false.\n\nWhen a reply is present, review.hasReply is true and review.reply is populated.\n","required":["id","event","review","account","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"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":"Account ID (same as id); canonical field for account filtering."},"platform":{"type":"string"},"username":{"type":"string"}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadReviewDeleted":{"type":"object","description":"Webhook payload for the review.deleted event.\n\nGoogle Business Profile stopped returning this review, for example after Google's spam filter removed it. Detected by polling, it usually fires 6 to 12 hours after the review disappears.\n\n- Opt-in: only locations covered by a webhook subscribed to review.deleted or review.restored are checked.\n- If the review comes back, review.restored fires. A review Google hides and later restores produces review.deleted and then review.restored.\n- A review.updated can arrive for a review reported by review.deleted. The next check restores it.\n- It may arrive for a review id you never received review.new for. Ignore ids you do not know.\n","required":["id","event","review","account","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["review.deleted"]},"review":{"type":"object","required":["id","platform","rating","createdAt","lastSeenAt"],"properties":{"id":{"type":"string","description":"Full review name, matching review.id on the review.new event (\"accounts/123/locations/456/reviews/789\")."},"platform":{"type":"string","enum":["googlebusiness"]},"rating":{"type":["integer","null"],"minimum":1,"maximum":5,"description":"Star rating the reviewer gave. Null when it was never recorded."},"createdAt":{"type":["string","null"],"format":"date-time","description":"When the reviewer posted the review. Null when it was never recorded."},"lastSeenAt":{"type":"string","format":"date-time","description":"Last time Zernio saw Google return this review."}}},"account":{"type":"object","required":["id","platform","username"],"properties":{"id":{"type":"string"},"accountId":{"type":"string","description":"Account ID (same as id); canonical field for account filtering."},"platform":{"type":"string"},"username":{"type":"string"}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadReviewRestored":{"type":"object","description":"Webhook payload for the review.restored event. Same shape as review.new.\n\nA review reported by review.deleted is returned by Google again.\n","required":["id","event","review","account","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["review.restored"]},"review":{"$ref":"#/components/schemas/ReviewWebhookReview"},"account":{"type":"object","required":["id","platform","username"],"properties":{"id":{"type":"string"},"accountId":{"type":"string","description":"Account ID (same as id); canonical field for account filtering."},"platform":{"type":"string"},"username":{"type":"string"}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"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 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"},"mediaProductType":{"type":"string","description":"Instagram only: the platform media product type (e.g. FEED, REELS, STORY, AD). Absent when the platform did not report it."},"isAiGenerated":{"type":"boolean","description":"Instagram only: whether Instagram labeled the media as AI-generated. Absent when the platform did not report it."},"isSharedToFeed":{"type":"boolean","description":"Instagram reels only: whether the reel is also shared to the main feed. Absent when the platform did not report it."},"mediaAudioType":{"type":"string","description":"Instagram only: audio type of the media (MUSIC or ORIGINAL_SOUND). Absent when the platform did not report it."},"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 /\npost.external.deleted. Fired by Zernio's background sync when it detects a\nnatively-authored post (e.g. a Google Business Profile localPost created in\nthe Google UI), NOT a post published through Zernio. Poll-driven (~hourly),\nnot real-time. On post.external.deleted, post.deletedAt is populated.\n","required":["id","event","post","account","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"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":"Account ID (same as id); canonical field for account filtering."},"platform":{"type":"string"},"username":{"type":"string"}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"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","sms"]},"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, share)"},"url":{"type":"string","description":"Where to fetch the attachment. The contract depends on direction and\nplatform: inbound WhatsApp media points at the authenticated\n`GET /v1/whatsapp/media/{mediaId}` and requires\n`Authorization: Bearer <your API key>`, while outgoing media carries the\nURL originally supplied and Instagram / Facebook / Telegram carry direct\nplatform CDN links that need no authentication.\n"},"payload":{"type":"object","description":"Additional attachment metadata","properties":{"voice":{"type":"boolean","description":"WhatsApp audio only. True for a voice note recorded in the WhatsApp client, false for an audio file."}}}}}},"sender":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"Sender's platform identifier. For WhatsApp this is the phone number\n(without leading `+`) when available, otherwise the `businessScopedUserId`.\nFor other platforms, the platform's own user ID.\n"},"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.\n\nOmitted 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).\n"},"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 `+`).\n\n**Nullable during the BSUID rollout (April 2026+).** WhatsApp users\nwho adopt a username can message businesses without exposing a phone\nnumber, so this field is omitted for them. Match by `businessScopedUserId`\ninstead. See `libs/whatsapp/docs/whatsapp-bsuid-migration.md`.\n"},"businessScopedUserId":{"type":"string","description":"WhatsApp only. Business-scoped user ID (BSUID), Meta's canonical\nidentifier for a WhatsApp user within your business. Present when\nMeta includes it in the inbound payload (rollout in progress since\nearly April 2026). **Recommended primary identity anchor** going\nforward; fall back to `phoneNumber` only when this field is absent.\n"},"parentBusinessScopedUserId":{"type":"string","description":"WhatsApp only. Parent BSUID for businesses with linked business\nportfolios. Omitted for standalone portfolios.\n"},"whatsappUsername":{"type":"string","description":"WhatsApp only. User's WhatsApp username (e.g. `jane.shop`). Not a\nstable identifier, because users can change it. Useful for display, not\nrecommended as an identity anchor.\n"},"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","description":"When the message was sent, as reported by the platform and passed through unmodified. Use it as the chronological ordering key.\n\nFull ISO 8601 date-time: Instagram and Facebook carry millisecond precision, while some platforms (for example WhatsApp and Telegram) report whole seconds. If two messages share the same value, fetch the conversation messages with sortOrder=desc for the deterministic order.\n"},"isRead":{"type":"boolean"}}},"InboxWebhookConversation":{"type":"object","description":"The conversation context included in inbox webhook payloads.","required":["id","platformConversationId","status"],"properties":{"id":{"type":"string","description":"Zernio's internal conversation id (also the message's conversationId). Accepted by every /v1/inbox/conversations/{conversationId} endpoint."},"platformConversationId":{"type":"string","description":"The platform's conversation id. This is the `id` GET /v1/inbox/conversations returns for the same conversation (on Instagram and Messenger it is the participant's IGSID / PSID), so key your records on it to match webhooks with list rows. Also accepted by the conversation endpoints."},"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.\n\nLets integrators join any inbox webhook back to the CRM Contact without looking at the sender, which matters for outgoing and delivery-status events whose sender is the business.\n"}}},"InboxWebhookConversationDetail":{"type":"object","description":"The conversation object included in conversation lifecycle webhook payloads (conversation.started, conversation.control_changed).","required":["id","platform","platformConversationId","participantName","status"],"properties":{"id":{"type":"string","description":"The platform's conversation id, equal to `conversation.platformConversationId` on inbox webhooks (whose `conversation.id` is Zernio's internal id). Both are accepted by the conversation endpoints."},"platform":{"type":"string","enum":["instagram","facebook","telegram","whatsapp","twitter","reddit","bluesky","sms","rcs","slack","tiktok","imessage"]},"platformConversationId":{"type":"string","description":"Same value as `id`."},"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. Lets integrators seed the CRM straight from `conversation.started` without waiting for the first `message.*` event.\n\nResolved by joining `participantId` to the ContactChannel collection (the same join used by message.*, reaction.received, and call.* webhooks). Best-effort: omitted when no channel matches or `participantId` is absent.\n"}}},"ConversationAdAttribution":{"type":["object","null"],"description":"The ad that opened the conversation, enriched from the ads Zernio syncs for the account owner. null when the conversation did not start from a Meta referral (ad click or ig.me / m.me ref link).\n\nMeta's referral carries the ad ID but no campaign or ad set ID.\n\n- Ad in your synced ads (`GET /v1/ads`): `synced` is true and the ad name, campaign, ad set and ad account come from there.\n- Otherwise: `synced` is false, `name` falls back to the ad title (Instagram, Facebook) or headline (WhatsApp) Meta sent with the click, and the other fields are null.\n\nA team member limited to some profiles, or a profile-scoped API key, is enriched only from ads it can list with `GET /v1/ads`; any other ad returns `synced` false.\n\nA non-null object with `adId` null is a referral that is not an ad click: an ig.me / m.me ref link (`name` null) or a WhatsApp click on a post (`ctwa_source_type` post, `name` is Meta's headline). Nothing is looked up and `synced` is false.\n","required":["adId","name","synced","campaignId","campaignName","adSetId","adSetName","adAccountId","adAccountName","platformPostId","isExternal"],"properties":{"adId":{"type":["string","null"],"description":"Meta's ad ID: `meta_ad_id` on Instagram and Facebook, `ctwa_source_id` on WhatsApp when `ctwa_source_type` is `ad`. Accepted by `GET /v1/ads/{adId}`."},"name":{"type":["string","null"],"description":"The synced ad's name, else the ad title or headline Meta sent."},"synced":{"type":"boolean","description":"True when the ad was found in your synced ads."},"campaignId":{"type":["string","null"],"description":"Meta campaign ID. Synced ads only."},"campaignName":{"type":["string","null"],"description":"Campaign name. Synced ads only."},"adSetId":{"type":["string","null"],"description":"Meta ad set ID. Synced ads only."},"adSetName":{"type":["string","null"],"description":"Ad set name. Synced ads only."},"adAccountId":{"type":["string","null"],"description":"Meta ad account ID (act_...). Synced ads only."},"adAccountName":{"type":["string","null"],"description":"Ad account name. Synced ads only."},"platformPostId":{"type":["string","null"],"description":"The post the ad promotes, from the synced ad or else Meta's `post_id` on the click."},"isExternal":{"type":["boolean","null"],"description":"True when the ad was created outside Zernio (synced from Ads Manager), false when created through Zernio, null when not synced."}}},"InboxConversationAdMetadata":{"type":["object","null"],"description":"Click attribution for a conversation that started from a Meta ad or a ref-tagged ig.me / m.me link, as Meta sent it. Absent when the conversation did not come from an attributable click. For the ad name, campaign and ad set, read `adAttribution`.\n\n**First referral wins.** Values come from the referral Meta delivers for the click. If the same person later arrives through another ad or link, the original values are kept. For the fresh referral per click, read the `message.received` / `referral.received` webhooks.\n\nOn Instagram Click-to-Direct, Meta usually delivers the ad post first as an attachment-only `share` / `ig_post` message with no referral, then attaches the referral to the next message.\n\nWhatsApp exception: when Meta omits `ctwa_clid` from the referral, a later Meta automatic event can supply it and refresh `ctwa_captured_at`. Treat `ctwa_captured_at` as when Zernio stored the value, not when the click happened.\n\n**Two key families, one per surface, never together:**\n\n- `ctwa_*`: WhatsApp Click-to-WhatsApp. The ad ID is `ctwa_source_id`. There is no `meta_ad_id` on WhatsApp.\n- `meta_ad_*`: Instagram Click-to-Direct, Facebook Messenger Click-to-Message, and ig.me / m.me ref links. The ad ID is `meta_ad_id` (ad clicks only; a link capture carries `meta_ad_ref` without it). `ctwa_clid` never appears here.\n\nEvery key is optional and only keys Meta supplied are returned, so read defensively. Meta sends no campaign or ad set ID; those are resolved from your synced ads in `adAttribution`. More keys may be added; treat unknown keys as opaque strings.\n\nKey names differ from the `message.received` webhook on purpose. The webhook forwards Meta's referral verbatim (`ad_id`, `source`, `type`), while the stored conversation uses the prefixed names. Renaming either side would break existing integrations, so both spellings stay.\n","properties":{"ctwa_clid":{"type":"string","description":"WhatsApp only. Meta's click identifier, the value to forward to the Meta Conversions API for Business Messaging. Meta omits it on some numbers, so a WhatsApp referral can arrive without it."},"ctwa_source_id":{"type":"string","description":"WhatsApp only. The Meta ad ID the user clicked (or the post ID when `ctwa_source_type` is post). This is the WhatsApp equivalent of meta_ad_id."},"ctwa_source_type":{"type":"string","description":"WhatsApp only. What the user clicked, as supplied by Meta (for example ad or post)."},"ctwa_source_url":{"type":"string","description":"WhatsApp only. Meta's URL for the ad that was clicked, normally an fb.me short link."},"ctwa_headline":{"type":"string","description":"WhatsApp only. Headline of the ad creative at click time."},"ctwa_body":{"type":"string","description":"WhatsApp only. Body text of the ad creative at click time."},"ctwa_media_type":{"type":"string","description":"WhatsApp only. Media type of the ad creative, image or video."},"ctwa_image_url":{"type":"string","description":"WhatsApp only. Image of the ad creative at click time (image ads)."},"ctwa_video_url":{"type":"string","description":"WhatsApp only. Video of the ad creative at click time (video ads)."},"ctwa_thumbnail_url":{"type":"string","description":"WhatsApp only. Thumbnail of the ad video at click time (video ads)."},"ctwa_captured_at":{"type":"string","format":"date-time","description":"WhatsApp only. When Zernio stored this referral. Always present when a WhatsApp referral was captured."},"meta_ad_id":{"type":"string","description":"Instagram and Facebook only. The Meta ad ID the user clicked. Present for ad clicks; absent when the capture came from an ig.me / m.me ref link."},"meta_ad_source":{"type":"string","description":"Instagram and Facebook only. Meta-supplied source identifier: ADS for ad clicks; SHORTLINK, SHORTLINKS or IGME-SOURCE-LINK for ref links (treat as opaque)."},"meta_ad_type":{"type":"string","description":"Instagram and Facebook only. Meta-supplied referral type, for example OPEN_THREAD."},"meta_ad_ref":{"type":"string","description":"Instagram and Facebook only. The ref parameter passed through from the ad creative or the ig.me / m.me link."},"meta_ad_title":{"type":"string","description":"Instagram and Facebook only. Title of the ad creative at click time."},"meta_ad_photo_url":{"type":"string","description":"Instagram and Facebook only. Image of the ad creative at click time."},"meta_ad_video_url":{"type":"string","description":"Instagram and Facebook only. Video of the ad creative at click time."},"meta_ad_post_id":{"type":"string","description":"Instagram and Facebook only. The organic post the ad promoted, when the ad was a boosted post."},"meta_ad_product_id":{"type":"string","description":"Instagram and Facebook only. The catalogue product the user clicked, for product ads."},"meta_ad_flow_id":{"type":"string","description":"Instagram and Facebook only. The Meta flow the ad launched, for flow ads."},"meta_ad_captured_at":{"type":"string","format":"date-time","description":"Instagram and Facebook only. When Zernio stored this referral. Always present when an Instagram or Facebook referral was captured."}}},"InboxWebhookAccount":{"type":"object","description":"The account context included in inbox webhook payloads.","required":["id","platform","username"],"properties":{"id":{"type":"string","description":"Account ID"},"accountId":{"type":"string","description":"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 ID this account belongs to. Use it to route or filter inbox webhooks by profile.\n\nThis 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.\n"},"platform":{"type":"string"},"username":{"type":"string"},"displayName":{"type":"string"},"pageId":{"type":"string","description":"The bare Facebook Page id behind the account, to route inbound messages by Page. Present for Facebook accounts and Instagram accounts connected through Facebook Login; omitted otherwise."}}},"WebhookPayloadReaction":{"type":"object","description":"Webhook payload for reaction received events (WhatsApp, Telegram, Slack, Instagram, Facebook Messenger, TikTok)","required":["id","event","reaction","conversation","account","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"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\n`removed` on WhatsApp (Meta does not report which emoji was removed),\nand on TikTok for an AI emoji reaction (TikTok sends no unicode for it).\n"},"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 WhatsApp, Slack, Instagram, Facebook Messenger and TikTok it is the business own platform id when the business reacted from the native app or via the reactions API: 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","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadReferral":{"type":"object","description":"Webhook payload for referral received events (Instagram, Facebook Messenger)","required":["id","event","referral","sender","conversation","account","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["referral.received"]},"referral":{"type":"object","description":"Meta's referral object, forwarded verbatim. Same shape as\n`metadata.referral` on `message.received`: `ref` + `source` for\nig.me / m.me links, `ad_id` + `ads_context_data` for returning\nMessenger ad clicks.\n","properties":{"ref":{"type":"string","description":"The `ref` parameter of the clicked ig.me / m.me link or ad."},"source":{"type":"string","description":"Meta-supplied source (`SHORTLINK`, `SHORTLINKS`, `IGME-SOURCE-LINK`, `ADS` - treat as opaque)."},"type":{"type":"string","description":"Meta-supplied referral type (e.g. `OPEN_THREAD`)."},"referer_uri":{"type":"string","description":"URI of the originating site, when Meta supplies one. Facebook Messenger only."},"ad_id":{"type":"string","description":"The Meta ad ID, on returning ad clicks. Facebook Messenger only."},"ads_context_data":{"type":"object","description":"Snapshot of the ad's public context at click time.","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"}}}}},"sender":{"type":"object","required":["id"],"description":"Who clicked - the conversation participant.","properties":{"id":{"type":"string","description":"Platform-scoped user ID (IGSID / PSID)."},"contactId":{"type":"string","description":"Zernio CRM Contact id for this sender, when one exists."}}},"conversation":{"$ref":"#/components/schemas/InboxWebhookConversation"},"account":{"$ref":"#/components/schemas/InboxWebhookAccount"},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"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: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"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","sms","rcs","twitter","bluesky","reddit","slack","tiktok","imessage"]},"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, share).\n\nInstagram and Facebook deliver a shared reel, post or ad with no type of its own (Meta's `unsupported_type`). Zernio resolves it from the media's Content-Type at ingest, so it arrives as `image`, `video`, `audio` or `file` with `originalType: \"unsupported_type\"`.\n\n`type: \"unsupported_type\"` itself is emitted only when the CDN could not be classified in time; the `url` still works.\n"},"originalType":{"type":"string","description":"Instagram and Facebook only, and present only when it differs\nfrom `type`. Meta's own attachment type before Zernio normalized\nit: `ig_reel` and `reel` become `video`, while `ig_post`, `post`,\n`ig_story` and `story_mention` all become `share`.\n\nRead it before rendering, because `type: \"share\"` alone is\nambiguous. In particular a story mention arrives as\n`type: \"share\"` with `originalType: \"story_mention\"`; treating an\nunrecognized type as a generic document shows your agent\n\"document received\" for what is usually a lead.\n\n`originalType: \"unsupported_type\"` marks a share Meta did not\nclassify, resolved by content type. **Download it on receipt**:\nMeta answers `is_unsupported` with no attachments when the\nmessage node is read back, so the attachment-resolve endpoint\ncannot re-mint this url once it expires.\n"},"mimeType":{"type":"string","description":"MIME type of the media when Zernio knows it. On Instagram and\nFacebook it is set for shares resolved by content type\n(`originalType: \"unsupported_type\"`).\n"},"url":{"type":"string","description":"Where to fetch the attachment. **The contract differs by platform.**\n\n- **WhatsApp**: points at `GET /v1/whatsapp/media/{mediaId}`, an authenticated Zernio endpoint. You MUST send `Authorization: Bearer <your API key>`; without it you get `401`. Download the bytes when this webhook arrives: Meta drops inbound media after a limited retention window, then the endpoint answers `400` permanently.\n- **Instagram / Facebook / Telegram**: a direct platform CDN link that needs no authentication and expires on the platform's own schedule.\n\n**Webhook attachments carry no `refreshUrl`.** It is stamped only when you read a message over REST (`GET /v1/inbox/conversations/{conversationId}/messages`).\n\nOn Instagram and Facebook the url is a signed, expiring Meta CDN link, so do not persist it. Store the message id and resolve media through `GET /v1/inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}?accountId={accountId}`, which re-mints it on demand.\n\nEvery value that URL needs is in this payload: `message.conversationId`, `message.platformMessageId`, `account.accountId`, and the attachment's zero-based position in this array.\n"},"payload":{"type":"object","description":"Additional attachment metadata","properties":{"voice":{"type":"boolean","description":"WhatsApp audio only. True for a voice note recorded in the WhatsApp client, false for an audio file."}}}}}},"sender":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"Sender's platform identifier. For WhatsApp this is the phone\nnumber (without leading `+`) when available, otherwise the\n`businessScopedUserId`.\n"},"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 `+`).\n\n**Nullable during the BSUID rollout (April 2026+).** WhatsApp\nusers who adopt a username can message businesses without\nexposing a phone number, so this field is omitted for them.\nMatch by `businessScopedUserId` instead. See\n`libs/whatsapp/docs/whatsapp-bsuid-migration.md`.\n"},"businessScopedUserId":{"type":"string","description":"WhatsApp only. Business-scoped user ID (BSUID), Meta's canonical\nidentifier for a WhatsApp user within your business. Present\nwhen Meta includes it in the inbound payload (rollout in\nprogress since early April 2026). **Recommended primary identity\nanchor** going forward; fall back to `phoneNumber` only when\nthis field is absent.\n"},"parentBusinessScopedUserId":{"type":"string","description":"WhatsApp only. Parent BSUID for businesses with linked business\nportfolios. Omitted for standalone portfolios.\n"},"whatsappUsername":{"type":"string","description":"WhatsApp only. User's WhatsApp username (e.g. `jane.shop`). Not a\nstable identifier, because users can change it. Useful for display,\nnot recommended as an identity anchor.\n"},"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","description":"When the message was sent, as reported by the platform and passed through unmodified. Full ISO 8601 date-time: Instagram and Facebook carry millisecond precision; some platforms (e.g. WhatsApp and Telegram) report whole seconds.\n\nUse it as the chronological ordering key. If two messages share a value, fetch the conversation messages with sortOrder=desc for the deterministic order.\n"},"isRead":{"type":"boolean"},"sentVia":{"type":["string","null"],"enum":["human","api","broadcast","sequence","workflow","comment_automation","bulk-api",null],"description":"Which Zernio surface produced the message. Always present and\nalways `null` on this event, since nobody on our side produced an\ninbound message; it is only informative on `message.sent`, which\ndocuments the vocabulary.\n"},"automationId":{"type":["string","null"],"description":"Always null on this event; see message.sent."},"workflowId":{"type":["string","null"],"description":"Always null on this event; see message.sent."},"executionId":{"type":["string","null"],"description":"Always null on this event; see message.sent."},"broadcastId":{"type":["string","null"],"description":"Always null on this event; see message.sent."},"sequenceId":{"type":["string","null"],"description":"Always null on this event; see message.sent."}}},"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, a quote-reply to an earlier message, an inbound another app is answering under Meta's handover protocol, or a TikTok DM that is not plain text)","properties":{"standby":{"type":"boolean","description":"true when this inbound arrived on Meta's standby path because another app owned the conversation: Meta Business Agent on WhatsApp, or another handover receiver (such as Page Inbox) on Facebook and Instagram. That app answers it; Zernio only observes and no automation runs. See conversation.control_changed.\n\nTo take control back:\n\n- WhatsApp: sending a reply takes control back.\n- Facebook, and Instagram accounts connected through a Facebook Page: take control first with POST /v1/inbox/conversations/{conversationId}/thread-control.\n- Instagram Login connections: cannot take or request control; wait for the owner to pass it.\n"},"quotedMessageId":{"type":"string","description":"Raw platform envelope id (WhatsApp `context.id`; Instagram and\nFacebook Messenger `reply_to.mid`) of the message this one is a\nquote-reply to, forwarded verbatim. It may not equal the stored\nid of that message (see `quotedMessage.platformMessageId`). On\noutgoing messages the same field appears on `message.sent`, but\nonly on some surfaces: see\nWebhookPayloadMessageSent.metadata.quotedMessageId.\n"},"quotedMessage":{"type":"object","description":"Zernio's own ids for the message this one quote-replies to. Present only when that message is stored; WhatsApp only today.","properties":{"messageId":{"type":"string","description":"Internal id of the stored quoted message."},"platformMessageId":{"type":"string","description":"The STORED message's platform id (what message.sent and list-messages return). Can differ from quotedMessageId, because Meta renders one message under a different wamid per perspective."}}},"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:\n`button_reply` (tap on an interactive button), `list_reply` (tap on a\nlist row), or `nfm_reply` (a WhatsApp Flow submission or an\n`address_message` submission, see `nfmReplyName`).\n"},"interactiveId":{"type":"string","description":"WhatsApp only. The `id` of the tapped button or list row, matching the\n`id` you supplied when the message was sent. Not set for Flow responses.\n"},"buttonPayload":{"type":"string","description":"WhatsApp only. Payload attached to a tapped template button. Template\nbuttons emit a plain `button` webhook (not an interactive reply), so\n`interactiveType` is empty while this field is populated.\n"},"flowResponseJson":{"type":"string","description":"WhatsApp only. Raw `nfm_reply.response_json` string returned by a\nFlow submission. Useful if you need the exact wire payload; for\ntyped access use `flowResponseData` instead.\n"},"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 Flow submitted.\n\nAn `address_message` submission (`nfmReplyName: address_message`) carries the address fields (`name`, `address`, `city`, `state`, `in_pin_code`, ...), either at the top level or nested under `values`; read both.\n"},"nfmReplyName":{"type":"string","description":"WhatsApp only. `nfm_reply.name` as Meta sent it, e.g. `flow` or\n`address_message`. Address submissions share the `nfm_reply`\nenvelope with Flow submissions and are otherwise indistinguishable\nin `flowResponseData`; use this field to tell them apart.\n"},"order":{"type":"object","description":"WhatsApp only. Cart submitted by the user from a commerce message\n(catalog, product, or product-list message). Meta's `order` object\nforwarded verbatim.\n","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\ninbound text carries Meta's `context.referred_product` (the user\ntapped \"Message business\" on a product). Forwarded verbatim.\n","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."}}},"forwarded":{"type":"boolean","description":"WhatsApp only. True when the user forwarded this message (5 times or fewer). Absent when not forwarded."},"frequentlyForwarded":{"type":"boolean","description":"WhatsApp only. True when the message was forwarded more than 5 times; Meta then omits forwarded."},"location":{"type":"object","description":"WhatsApp only. The location pin the user shared, forwarded\nverbatim from Meta. The message `text` is only the emoji preview\n(`📍 <name>`); the coordinates live here.\n","properties":{"latitude":{"type":"number","description":"Latitude in decimal degrees."},"longitude":{"type":"number","description":"Longitude in decimal degrees."},"name":{"type":"string","description":"Location name, when the user shared a named place."},"address":{"type":"string","description":"Street address, when Meta sends one."}}},"contacts":{"type":"array","description":"WhatsApp only. Contact cards the user shared, forwarded verbatim\nfrom Meta. Read `contactsOrigin` before treating any number here\nas the sender's own.\n","items":{"type":"object","additionalProperties":true}},"contactsOrigin":{"type":"string","enum":["contact_request","other"],"description":"WhatsApp only. How the contact card was shared. Omitted when Meta sends no origin.\n\n- `contact_request`: the user tapped a `request_contact_info` button, so the number is their own and consented.\n- `other`: they picked a card from their address book. It may be anyone's and must NOT be stored as the sender's identity.\n"},"storyReply":{"type":"object","description":"Instagram only. Populated when an IG user replies to one of the\naccount's stories (Meta `messaging_story_replies`). Mutually\nexclusive in practice with `isStoryMention`.\n","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\n24 hours after the story posted; consumers must fetch\npromptly or treat 404s as expected.\n"}}},"isStoryMention":{"type":"boolean","description":"Instagram only. True when the message was generated by an IG\nuser mentioning the account in their own story (`story_mention`\nattachment type). Mutually exclusive in practice with `storyReply`.\n"},"referral":{"type":["object","null"],"description":"Click attribution forwarded verbatim from Meta. Present only on the first inbound message Meta attaches it to; absent on later messages of the same conversation.\n\nThat is not always the first message after the click. On Instagram Click-to-Direct, Meta usually delivers the ad post first as an attachment-only `share` / `ig_post` message with no referral, and attaches the referral to the next message.\n\nThe conversation's first referral is also stored as `metadata.meta_ad_*` (`GET /v1/inbox/conversations/{conversationId}`); read it there instead of matching webhooks.\n\nOn Instagram and Messenger, a RETURNING click also attaches it to the next message, so read it on every `message.received` for per-click attribution. A click that opens an existing thread WITHOUT a message arrives as a separate `referral.received` event.\n\nThe populated subset identifies the source:\n\n- `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.\n- `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.\n- `ref` without `ad_id`: an ig.me / m.me link with a `?ref=` parameter (`source` is `SHORTLINK`, `SHORTLINKS` or `IGME-SOURCE-LINK` depending on surface; treat it as opaque). Instagram delivers ig.me refs on new threads only when the account has at least one Ice Breaker (`PUT /v1/accounts/{accountId}/instagram-ice-breakers`).\n","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"},"welcome_message":{"type":"object","description":"WhatsApp CTWA only. The greeting Meta showed the user in the ad.","properties":{"text":{"type":"string"}}},"ad_id":{"type":"string","description":"Facebook Messenger CTM / Instagram CTD only. The Meta ad ID the\nuser clicked to start the conversation.\n"},"ref":{"type":"string","description":"The `ref` parameter passed through from the Meta ad creative\nor from an ig.me / m.me link. Instagram / Facebook Messenger\nonly.\n"},"source":{"type":"string","description":"Meta-supplied source identifier (`ADS` for ad clicks;\n`SHORTLINK`, `SHORTLINKS` or `IGME-SOURCE-LINK` for ref\nlinks). Instagram / Facebook Messenger only.\n"},"type":{"type":"string","description":"Meta-supplied referral type (e.g. `OPEN_THREAD`). Instagram /\nFacebook Messenger only.\n"},"referer_uri":{"type":"string","description":"URI of the originating site, when Meta supplies one (m.me\nlinks opened from the web). Facebook Messenger only.\n"},"ads_context_data":{"type":"object","description":"Snapshot of the ad's public context at click time. Facebook\nMessenger CTM / Instagram CTD only.\n","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"}}}}},"ad":{"allOf":[{"$ref":"#/components/schemas/ConversationAdAttribution"}],"description":"The click enriched from your synced ads: the ad name, campaign, ad set and ad account Zernio holds for this ad ID.\n\n**Present with `referral`** whenever the referral is attributable:\n\n- Instagram and Facebook: every forwarded referral (an `ad_id` or a `ref`).\n- WhatsApp: a referral carrying `ctwa_clid`, `source_id`, `source_url` or `headline`.\n\nBuilt from this message's referral, so it follows a returning click, while the conversation's `adAttribution` keeps the first one.\n"},"unsupported":{"type":"object","description":"WhatsApp only. Meta's own reason this message has no\nrenderable body. Present when Meta attached an error to the\ninbound payload; in practice the `unsupported`, `errors` and\n`unknown` types (code 131051: message type currently not\nsupported). `text` on those messages is the fixed\n`[Unsupported message]` placeholder.\n\nAlso present with code 131052 when Meta could not download\nmedia the sender attached, except on numbers also using the\nWhatsApp Business app. The file is not available, so the sender\nhas to send it again.\n","properties":{"code":{"type":"integer","description":"Meta's numeric error code (e.g. 131051)."},"title":{"type":"string","description":"Meta's short error title."},"details":{"type":"string","description":"Meta's human-readable error detail string."},"type":{"type":"string","description":"Meta's name for the content WhatsApp could not deliver, e.g. view_once, poll_creation, group_invite, edit. Absent when Meta sends none."}}},"noRenderableContent":{"type":"boolean","description":"Instagram / Facebook Messenger only. Set when the message carries nothing an integrator can render: a `template` attachment with no text and no parseable content, or Meta's own `is_unsupported` flag.\n\nSibling of `unsupported` above (WhatsApp only, carries Meta's error code/title/details and unsupported type); this field has no error envelope, only the boolean.\n\nAbsence means \"not flagged\", never \"checked and renderable\".\n"},"tiktokMessageType":{"type":"string","description":"TikTok only. The message type as TikTok reports it, forwarded verbatim (for example image, video, sticker, share_post, emoji, reaction, template).\n\nPresent on every TikTok DM that is not plain text. Those arrive with text empty and, for image, video, share_post, sticker and emoji, an attachment:\n\n- share_post: type share, with the embed url and payload.videoId.\n- sticker/emoji: type sticker, url signed and expiring.\n"}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"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: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"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","twitter","reddit","bluesky","slack","tiktok","imessage"],"description":"Every platform whose outgoing messages Zernio observes. sms is absent on purpose: its carrier receipts update delivery status and never raise message.sent."},"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, share)"},"originalType":{"type":"string","description":"Instagram and Facebook only, and present only when it differs from `type`. Meta's own attachment type before Zernio normalized it. See the same field on message.received for the full mapping."},"url":{"type":"string","description":"Where to fetch the attachment. For outgoing messages this is the media URL as sent. On WhatsApp it is the URL you supplied when publishing (WhatsApp sends media by link), not a Zernio endpoint, and it needs no Zernio credentials.\n\nContrast the inbound direction: `message.received` attachment URLs on WhatsApp point at the authenticated `GET /v1/whatsapp/media/{mediaId}`.\n\nAs on `message.received`, webhook attachments carry no `refreshUrl`: that field is stamped only on the REST read. Resolve Instagram and Facebook media through `GET /v1/inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}?accountId={accountId}`.\n"},"payload":{"type":"object","description":"Additional attachment metadata"}}}},"sender":{"type":"object","required":["id"],"description":"**On this event the sender is your own business, not the person you\nare talking to.** `id` is the Zernio account id and `name`,\n`username` and `picture` are that connected account's own profile.\n\nDo not read these to name or update a contact: doing so on an echo\nrelabels the customer's record with your business name. The other\nparty is `conversation.participantId` / `participantName` /\n`participantUsername`, which are populated in both directions.\n","properties":{"id":{"type":"string","description":"The Zernio account id of the connected account that sent the message, not a contact id."},"contactId":{"type":"string","description":"Always omitted on this event: the sender is the business, not a contact. Use conversation.contactId to join back to the CRM Contact."},"name":{"type":"string","description":"Display name of your connected account."},"username":{"type":"string","description":"Username of your connected account."},"picture":{"type":"string","description":"Profile picture of your connected account."}}},"sentAt":{"type":"string","format":"date-time","description":"When the message was sent, as reported by the platform and passed through unmodified. Full ISO 8601 date-time: Instagram and Facebook carry millisecond precision; some platforms (for example WhatsApp and Telegram) report whole seconds.\n\nUse it as the chronological ordering key. If two messages share the same value, fetch the conversation messages with sortOrder=desc for the deterministic order.\n"},"isRead":{"type":"boolean"},"source":{"type":"string","enum":["whatsapp_business_app","cloud_api","meta_business_agent"],"description":"WhatsApp send origin. Absent on non-WhatsApp platforms.\n\n- whatsapp_business_app: sent from the WhatsApp Business phone app on a Coexistence number.\n- cloud_api: sent through Zernio (dashboard, API, or broadcasts).\n- meta_business_agent: Meta Business Agent answered on the number.\n\nSays where WhatsApp saw the send come from, not which Zernio surface produced it: read sentVia for that.\n"},"sentVia":{"type":["string","null"],"enum":["human","api","broadcast","sequence","workflow","comment_automation","bulk-api",null],"description":"Which Zernio surface produced this message. Same vocabulary as the `source` filter on the inbox analytics endpoints, and the same value a later GET on this message returns.\n\n- `human`: an operator in the Zernio inbox\n- `api`: a call to this API\n- `broadcast`\n- `sequence`\n- `workflow`\n- `comment_automation`\n- `bulk-api`: POST /v1/whatsapp/bulk\n\nAlways present, and `null` whenever the lineage is unknown:\n\n- any outgoing message not sent through Zernio (one typed in the platform's own app, a Meta automated reply such as an instant reply or away message, the echo of a click-to-message ad's greeting)\n- every message stored before this field shipped (2026-08)\n\nExisting messages are NOT backfilled, so treat `null` as \"unknown\", never as \"sent by a human\".\n"},"automationId":{"type":["string","null"],"description":"The comment automation that sent this DM (sentVia comment_automation). Null otherwise."},"workflowId":{"type":["string","null"],"description":"The workflow whose run sent this message (sentVia workflow). Null otherwise."},"executionId":{"type":["string","null"],"description":"The workflow run (execution) that sent this message, as returned by the workflow executions endpoints. Null when workflowId is null."},"broadcastId":{"type":["string","null"],"description":"The broadcast that sent this message (sentVia broadcast). Null otherwise."},"sequenceId":{"type":["string","null"],"description":"The sequence whose step sent this message (sentVia sequence). Null otherwise."}}},"pricing":{"$ref":"#/components/schemas/WhatsAppMessagePricing"},"billingConversation":{"$ref":"#/components/schemas/WhatsAppBillingConversation"},"conversation":{"$ref":"#/components/schemas/InboxWebhookConversation"},"account":{"$ref":"#/components/schemas/InboxWebhookAccount"},"metadata":{"type":"object","description":"Platform-specific context for the sent message: a quote-reply reference, a WhatsApp location pin, WhatsApp contact cards, the TikTok message type, or outgoing Instagram/Facebook buttons, quick replies and template.\n\nThe key is present only when the send carried some context: it is never null and never an empty object. Read it to tell a location or contact-card message from a text one without a GET on the message.\n","properties":{"metaInteractive":{"type":"object","description":"Instagram/Facebook only. The buttons, quickReplies and/or template this outgoing message carried, as sent (tracked urls included when link tracking wrapped a button). Absent when the send carried none.","additionalProperties":true},"location":{"type":"object","description":"WhatsApp only. The location pin this message carries, in the same shape the inbox send API accepts.\n\nPresent on API sends that passed `location`, and on Coexistence echoes of a pin shared from the WhatsApp Business app.\n\nThe message `text` is only the emoji preview (`📍 <name>`); the pin itself lives here.\n","properties":{"latitude":{"type":"number","description":"Latitude in decimal degrees."},"longitude":{"type":"number","description":"Longitude in decimal degrees."},"name":{"type":"string","description":"Location name, when one was given."},"address":{"type":"string","description":"Street address, when one was given."}}},"contacts":{"type":"array","description":"WhatsApp only. The contact cards this message carries. The message `text` is only the emoji preview (`👤 <name>`); the cards live here.\n\n- API sends: the `contacts` array exactly as given to the inbox send API (`name`, `phones[].phone` / `type`, `emails[]`).\n- Coexistence echoes of a card shared from the WhatsApp Business app: Meta's shape (`phones[].wa_id`, `vcard`).\n","items":{"type":"object","additionalProperties":true}},"quotedMessageId":{"type":"string","description":"`platformMessageId` of the message this send quote-replies to.\n\n- **WhatsApp and Telegram:** present when the reply was sent through Zernio with `replyTo` on the inbox send API. A WhatsApp API send fires `message.sent` off the delivery status, with the quote reference forwarded from the stored send, so it arrives on the same `message.sent` as any WhatsApp send.\n- **Instagram echoes:** not delivered. Zernio forwards `reply_to.mid` whenever Meta puts it on an echo, but on Instagram Meta does not send it, so a reply the operator quoted in the Instagram app arrives with no `quotedMessageId`.\n- **Facebook Messenger:** uses a separate subscription (`message_echoes`) that has not been measured. Treat it as unverified, not supported.\n- **WhatsApp Coexistence echoes:** absent. Meta omits the quote context from `smb_message_echoes`, so a reply the operator sent from the WhatsApp Business app has no `quotedMessageId` even though WhatsApp shows it as a quote-reply.\n\nDo not read the absence of this field as \"not a reply\".\n"},"threadTs":{"type":"string","description":"Slack only. Parent thread ts of the sent message. Pass it back as\n`replyTo` on the inbox send API to keep replying inside the thread.\n"},"tiktokMessageType":{"type":"string","description":"TikTok only. The message type as TikTok reports it, forwarded verbatim (for example image, video, sticker, share_post, emoji, reaction, template).\n\nPresent on every TikTok DM that is not plain text. Those arrive with text empty and, for image, video, share_post, sticker and emoji, an attachment:\n\n- share_post: type share, with the embed url and payload.videoId.\n- sticker/emoji: type sticker, url signed and expiring.\n\nAbsent on image sends made through the Zernio API, which carry the image in attachments.\n"}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"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\nedits a previously-sent message. Supported platforms: Instagram,\nFacebook Messenger, Telegram, WhatsApp. The message object reflects the\nLATEST state; editHistory contains every prior version in order\n(oldest first), so the last entry is the version immediately before\nthe current content.\n","required":["id","event","message","editHistory","editCount","editedAt","conversation","account","timestamp"],"properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"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","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadMessageDeleted":{"type":"object","description":"Webhook payload for message.deleted events. Fires when the sender deletes (unsends) a message. Read `message.direction` to tell the directions apart.\n\n- Instagram: incoming unsend.\n- WhatsApp, both directions: an outgoing message the business deleted (via the Cloud API, or from the WhatsApp Business app on a Coexistence number), and an incoming message the customer deleted.\n\nmessage.text and message.attachments retain the content from before the delete. The Zernio dashboard does not show it, but authorized API consumers may access it for moderation, compliance, or archival use.\n","required":["id","event","message","deletedAt","conversation","account","timestamp"],"properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"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","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadMessageDeliveryStatus":{"type":"object","description":"Shared payload for message.delivered, message.read, message.played and message.failed events. Fires when the platform reports a new delivery state for an outgoing message.\n\n**Platform support:**\n\n- message.delivered: WhatsApp, Facebook Messenger, SMS, RCS.\n- message.read: WhatsApp, Facebook Messenger, Instagram, RCS. Not SMS (carriers report delivery, never read).\n- message.played: WhatsApp only, voice messages.\n- message.failed: WhatsApp, SMS and RCS (other platforms don't expose per-message failure via webhook). On SMS, `error.code` is the carrier's numeric code and `error.message` its reason.\n","required":["id","event","message","statusAt","conversation","account","timestamp"],"properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"event":{"type":"string","enum":["message.delivered","message.read","message.played","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"},"details":{"type":"string","description":"Platform's extended detail for `code` (WhatsApp: Meta's `error_data.details`), when the platform sent one. Absent on SMS."},"href":{"type":"string","format":"uri","description":"Link to the platform's documentation for `code`, when the platform sent one."},"explanation":{"type":["string","null"],"description":"Plain-language translation of `code` (e.g. for 131026, that the\nrecipient has likely opted out of marketing messages while utility\ntemplates are unaffected, or for 131031, that Meta restricted the\nWhatsApp Business Account). Null for unmapped codes; fall back to\ntitle/message.\n"}}},"pricing":{"$ref":"#/components/schemas/WhatsAppMessagePricing"},"billingConversation":{"$ref":"#/components/schemas/WhatsAppBillingConversation"},"conversation":{"$ref":"#/components/schemas/InboxWebhookConversation"},"account":{"$ref":"#/components/schemas/InboxWebhookAccount"},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WhatsAppMessagePricing":{"type":["object","null"],"description":"WhatsApp only. Meta's `pricing` object from the status webhook, camelCased.\nPresent (possibly null) on every WhatsApp `message.sent`, `message.delivered`,\n`message.read` and `message.failed`; absent on other platforms. Meta includes it\non `sent` and on one of `delivered` or `read`, so it is null on the others and\nusually on `failed`.\n","required":["billable","pricingModel","category","type"],"properties":{"billable":{"type":["boolean","null"],"description":"Whether Meta bills this message. Meta has announced it will deprecate this field."},"pricingModel":{"type":["string","null"],"description":"`PMP` (per-message pricing) or `CBP` (conversation-based, messages before 2025-07-01).","example":"PMP"},"category":{"type":["string","null"],"description":"Pricing category as Meta sends it, for example `marketing`, `marketing_lite`, `utility`, `authentication`, `authentication-international`, `service`, `referral_conversion`.","example":"marketing"},"type":{"type":["string","null"],"description":"`regular` (billable), `free_customer_service` or `free_entry_point`.","example":"regular"}}},"WhatsAppBillingConversation":{"type":["object","null"],"description":"WhatsApp only. Meta's `conversation` object from the status webhook (the billing\nwindow, not the Zernio inbox `conversation`). Same presence rules as `pricing`;\nfrom Graph API v24 Meta sends it only inside an open free entry point window.\n","required":["id","expiresAt","originType"],"properties":{"id":{"type":["string","null"],"description":"Meta's conversation id."},"expiresAt":{"type":["string","null"],"format":"date-time","description":"When the window expires. Meta sends it only on the `sent` status."},"originType":{"type":["string","null"],"description":"Meta `origin.type`, for example `marketing`, `utility`, `service`, `referral_conversion`.","example":"utility"}}},"WebhookPayloadConversationStarted":{"type":"object","description":"Fired once when a new conversation begins, in either direction: the first time an account and a contact exchange a message on any DM platform (Instagram, Messenger/Facebook, Telegram, WhatsApp, X, Reddit, Bluesky, SMS, TikTok). One subscription covers every DM platform.\n\n**Ad attribution**: `conversation.metadata` (the referral as Meta sent it) and `conversation.adAttribution` (the ad, campaign and ad set from your synced ads) are filled only when the message that created the conversation carried Meta's referral.\n\n- WhatsApp Click-to-WhatsApp, Facebook Messenger Click-to-Message, and ig.me / m.me ref links: it does.\n- Instagram Click-to-Direct: it usually does NOT. Meta creates the thread with the ad post itself (an attachment-only `share` / `ig_post` message with no referral) and attaches the referral to the next message, so this event has `adAttribution` null and no `metadata`.\n\nFor Instagram, read the click from `metadata.ad` and `metadata.referral` on the following `message.received`, or from `adAttribution` on `GET /v1/inbox/conversations` and `GET /v1/inbox/conversations/{conversationId}`, which carry it once the referral is stored.\n","required":["id","event","conversation","account","startedAt","timestamp"],"properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"event":{"type":"string","enum":["conversation.started"]},"conversation":{"allOf":[{"$ref":"#/components/schemas/InboxWebhookConversationDetail"},{"type":"object","required":["adAttribution"],"properties":{"metadata":{"$ref":"#/components/schemas/InboxConversationAdMetadata"},"adAttribution":{"$ref":"#/components/schemas/ConversationAdAttribution"}}}]},"account":{"$ref":"#/components/schemas/InboxWebhookAccount"},"startedAt":{"type":"string","format":"date-time","description":"When the conversation document was created."},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"MessengerGreeting":{"type":"object","required":["locale","text"],"properties":{"locale":{"type":"string","description":"Meta locale, e.g. `default`, `en_US`, `es_ES`."},"text":{"type":"string","minLength":1,"maxLength":160}}},"MessengerIceBreakerLocale":{"type":"object","required":["locale","call_to_actions"],"properties":{"locale":{"type":"string","description":"Meta locale, e.g. `default`, `en_US`."},"call_to_actions":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"object","required":["question","payload"],"properties":{"question":{"type":"string","minLength":1,"maxLength":80},"payload":{"type":"string","minLength":1,"maxLength":1000,"description":"Postback payload sent on tap. `zernio:workflow:<workflowId>` starts that workflow."}}}}}},"WhatsAppConversationalAutomation":{"type":"object","properties":{"enable_welcome_message":{"type":"boolean","description":"When true, Meta sends a `request_welcome` event the first time a person opens a chat with the number."},"prompts":{"type":"array","maxItems":3,"description":"Ice breakers shown to a person opening a chat. Tapping one sends its text as a normal message.","items":{"type":"string","minLength":1,"maxLength":80}},"commands":{"type":"array","maxItems":30,"description":"Slash commands shown when a person types `/`. Names are unique, letters, digits and underscores, without the slash.","items":{"type":"object","required":["command_name","command_description"],"properties":{"command_name":{"type":"string","minLength":1,"maxLength":30,"pattern":"^[a-zA-Z0-9_]+$"},"command_description":{"type":"string","minLength":1,"maxLength":256}}}}}},"WebhookPayloadConversationControlChanged":{"type":"object","description":"Who answers a conversation changed under Meta's handover protocol. WhatsApp: Meta\nBusiness Agent took it over, handed it to you, or another partner app took it.\nFacebook and Instagram: another app passed the thread to you, or took or received it.\n","required":["id","event","conversation","account","control","changedAt","timestamp"],"properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"event":{"type":"string","enum":["conversation.control_changed"]},"conversation":{"$ref":"#/components/schemas/InboxWebhookConversationDetail"},"account":{"$ref":"#/components/schemas/InboxWebhookAccount"},"control":{"type":"object","required":["owner","previousOwner"],"properties":{"owner":{"type":"string","enum":["app","ai_agent","other"],"description":"Who answers now. ai_agent: Meta Business Agent (WhatsApp); app: you; other: another app (a WhatsApp partner, or a Messenger / Instagram receiver such as Page Inbox)."},"previousOwner":{"type":["string","null"],"enum":["app","ai_agent","other",null],"description":"Owner before this change, null when no handover had touched the thread."},"ownerAppId":{"type":"string","description":"Meta app id of the new owner, when Meta names it (Facebook and Instagram handovers, WhatsApp partner apps). Page Inbox is 263902037430900."},"metadata":{"type":"string","description":"Free-form string the transferring app attached to the handover, forwarded verbatim."}}},"changedAt":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"CallRecord":{"type":"object","description":"One call on a number you own, either channel. `channel` tells you which\nlane it took: `whatsapp` (WhatsApp Business Calling) or `pstn` (a regular\nphone call). List endpoints omit `transcript`; use `lastTranscriptSnippet`\nfor a preview and the detail endpoint for the full transcript.\n","properties":{"_id":{"type":"string"},"accountId":{"type":"string","description":"Owning 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\ninbound (UIC) and outbound (BIC) calls; branch on\n`call.direction` to tell them apart.\n","required":["id","event","call","account","timestamp"],"properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"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","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadCallEnded":{"type":"object","description":"Webhook payload for the `call.ended` event. Fires on call hangup\nwith the duration and a zero-markup billing breakdown.\n","required":["id","event","call","account","timestamp"],"properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"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"]},"hangupCause":{"type":["string","null"],"description":"Raw carrier hangup cause behind endReason (e.g. normal_clearing, call_rejected, not_found). Null when the carrier reported none."},"sipHangupCause":{"type":["string","null"],"description":"SIP response code that ended the call when SIP-signalled (e.g. '403', '486', '603'). endReason collapses all three to 'rejected', so this is what separates a refused destination from a busy line. Null on non-SIP legs."},"isVoicemail":{"type":"boolean","description":"True when the inbound call was handled by voicemail, whether scheduled or because the forward did not connect."},"callErrors":{"type":"array","description":"Failures recorded on the call up to hangup (bridge failed, dial failed, recording error). Empty on a clean call.\n\n- `message` is free-form diagnostic text and is not stable; do not parse it.\n- `code` is 0 unless a provider code is known.\n\nErrors the carrier reports after hangup appear only on GET /v1/calls/{id}.\n","items":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}},"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","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadCallFailed":{"type":"object","description":"Webhook payload for the `call.failed` event. Fired when a call\nsetup or in-progress call fails.\n","required":["id","event","call","account","timestamp"],"properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"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","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadCallPermissionRequest":{"type":"object","description":"Webhook payload for the `call.permission_request` event. Fires\nwhen a consumer accepts or rejects an interactive\n`call_permission_request` message.\n","required":["id","event","permission","account","timestamp"],"properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"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","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadAdVideoProcessed":{"type":"object","description":"Webhook payload for the `ad.video.processed` event. Fires once per\n`POST /v1/ads/videos` call made with `async: true`, when Meta finishes\nprocessing the video (Meta only).\n","required":["id","event","account","video","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["ad.video.processed"]},"account":{"type":"object","description":"The connected ads account the video was uploaded with.","required":["accountId","profileId","platform","username"],"properties":{"accountId":{"type":"string","description":"Internal Zernio account ID."},"profileId":{"type":"string","description":"Internal Zernio profile ID this account belongs to."},"platform":{"type":"string","description":"Ads connection platform. Currently always `metaads`.","example":"metaads"},"username":{"type":"string"},"displayName":{"type":["string","null"]}}},"video":{"type":"object","required":["id","platformAdAccountId","status","error","thumbnailUrl"],"properties":{"id":{"type":"string","description":"Meta video id, as returned by the 202 upload response."},"platformAdAccountId":{"type":"string","description":"Meta ad account id (act_<n>) the video was uploaded to."},"status":{"type":"string","enum":["ready","error"],"description":"`ready`: usable as `video.id` on the create endpoints. `error`: Meta could not process it; upload again."},"error":{"type":["string","null"],"description":"Meta's processing error when status is `error`, otherwise null."},"thumbnailUrl":{"type":["string","null"],"description":"Meta's auto-generated poster when status is `ready` and Meta produced one, otherwise null."}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event."}}},"WebhookPayloadAdCreated":{"type":"object","description":"Webhook payload for the `ad.created` event. Fires when an ad is created through Zernio (API, MCP or dashboard) or detected by the sync, once per ad, after its campaign and ad set are recorded so `GET /v1/ads/{adId}` finds them.\n\n`source` is `zernio` for ads created through Zernio and `platform` for ads our sync detected, up to one sync interval later (Meta ads entering review usually arrive within minutes). History loaded when an account connects, and ads created more than 7 days ago, are never announced.\n\nAn ad is announced at most once per 24 hours.\n","required":["id","event","account","adObject","source","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["ad.created"]},"account":{"$ref":"#/components/schemas/WebhookAdsAccount"},"adObject":{"type":"object","required":["level","platformId","platformAdAccountId","adId","name","campaign","adSet"],"properties":{"level":{"type":"string","enum":["AD"],"description":"Always `AD`."},"platformId":{"type":"string","description":"Platform-native ad ID."},"platformAdAccountId":{"type":"string","description":"Platform-native ad account ID."},"adId":{"type":"string","description":"Zernio ad ID, usable with GET /v1/ads/{adId}."},"name":{"type":"string"},"campaign":{"type":["object","null"],"description":"The campaign the ad belongs to, or null when the platform has none.","required":["platformCampaignId","name"],"properties":{"platformCampaignId":{"type":"string"},"name":{"type":["string","null"]}}},"adSet":{"type":["object","null"],"description":"The ad set the ad belongs to, or null when the platform has none.","required":["platformAdSetId","name"],"properties":{"platformAdSetId":{"type":"string"},"name":{"type":["string","null"]}}}}},"source":{"type":"string","enum":["zernio","platform"],"description":"Where the ad was created. `zernio` for ads created through Zernio, `platform` for ads the sync detected."},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event."}}},"WebhookPayloadAdUpdated":{"type":"object","description":"Webhook payload for the `ad.updated` event. Fires when an ad is edited through Zernio (API, MCP or dashboard), after the platform and Zernio both accepted the edit, or when the sync detects an edit made outside Zernio. It is sent once, to the owner of the edited ad.\n\n`source` is `zernio` for edits through Zernio, `platform` for edits the sync detected outside Zernio, up to one sync interval late. From the sync, `changes` covers only `name` and `status`.\n\nBudget, bid, schedule and targeting edits made outside Zernio are not announced on the ad. Never for history loaded when an account connects. Tracking tag edits are not announced, and an ad rule that changes an ad arrives as `ad_rule.triggered`.\n\n`platformId` can change when a LinkedIn creative is replaced, while `adId` stays stable.\n\n`changes` names the edited fields and never their values: read the ad with `GET /v1/ads/{adId}` for the current state. Ignore values you do not know, new ones can be added.\n\nEvents are not deduplicated: every edit is announced. Use the event `id` to drop repeats.\n","required":["id","event","account","adObject","changes","source","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["ad.updated"]},"account":{"$ref":"#/components/schemas/WebhookAdsAccount"},"adObject":{"type":"object","required":["level","platformId","platformAdAccountId","adId","name","campaign","adSet"],"properties":{"level":{"type":"string","enum":["AD"],"description":"Always `AD`."},"platformId":{"type":"string","description":"Platform-native ad ID."},"platformAdAccountId":{"type":"string","description":"Platform-native ad account ID."},"adId":{"type":"string","description":"Zernio ad ID, usable with GET /v1/ads/{adId}."},"name":{"type":"string"},"campaign":{"type":["object","null"],"description":"The campaign the ad belongs to, or null when the platform has none.","required":["platformCampaignId","name"],"properties":{"platformCampaignId":{"type":"string"},"name":{"type":["string","null"]}}},"adSet":{"type":["object","null"],"description":"The ad set the ad belongs to, or null when the platform has none.","required":["platformAdSetId","name"],"properties":{"platformAdSetId":{"type":"string"},"name":{"type":["string","null"]}}}}},"changes":{"type":"array","description":"Fields edited by this request. `status` is the ad's own on/off switch. Ignore values you do not know.","items":{"type":"string","enum":["name","status","budget","bid","schedule","targeting","creative","settings"]}},"source":{"type":"string","enum":["zernio","platform"],"description":"Where the edit was made. `zernio` for edits through Zernio, `platform` for edits the sync detected outside Zernio."},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event."}}},"WebhookPayloadCampaignCreated":{"type":"object","description":"Webhook payload for the `campaign.created` event. Fires when a campaign is created through Zernio (API, MCP or dashboard) or detected by the sync, once per campaign, after its row is recorded so `GET /v1/ads/campaigns/{campaignId}` finds it.\n\n`source` is `zernio` for campaigns created through Zernio and `platform` for campaigns our sync detected, up to one sync interval later. History loaded when an account connects, and campaigns created more than 7 days ago, are never announced.\n\nA campaign is announced at most once per 24 hours.\n","required":["id","event","account","adObject","source","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["campaign.created"]},"account":{"$ref":"#/components/schemas/WebhookAdsAccount"},"adObject":{"type":"object","required":["level","platformId","platformAdAccountId","name"],"properties":{"level":{"type":"string","enum":["CAMPAIGN"],"description":"Always `CAMPAIGN`."},"platformId":{"type":"string","description":"Platform-native campaign ID, usable as campaignId with /v1/ads/campaigns/{campaignId}."},"platformAdAccountId":{"type":"string","description":"Platform-native ad account ID."},"name":{"type":["string","null"]}}},"source":{"type":"string","enum":["zernio","platform"],"description":"Where the campaign was created. `zernio` for campaigns created through Zernio, `platform` for campaigns the sync detected."},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event."}}},"WebhookPayloadCampaignUpdated":{"type":"object","description":"Webhook payload for the `campaign.updated` event. Fires when a campaign is edited through Zernio (API, MCP or dashboard), after the platform and Zernio both accepted the edit, once per user who can see the campaign. It also fires when the sync detects an edit made outside Zernio.\n\n`source` is `zernio` for edits through Zernio, `platform` for edits the sync detected outside Zernio, up to one sync interval late, sent only to the user whose sync saw it.\n\nFrom the sync, `changes` covers only `name`, `status` and `schedule` (schedule only on Google, LinkedIn, Pinterest and OpenAI Ads). Budget edits made outside Zernio are not announced. Never for history loaded when an account connects. An ad rule that changes a campaign arrives as `ad_rule.triggered`.\n\nAd set edits and Google sub-resource edits (ad schedule, targeting, negative keywords, conversion goals, assets, asset groups, listing group filters) are not announced.\n\n`changes` names the edited fields and never their values: read the campaign with `GET /v1/ads/campaigns/{campaignId}` for the current state. Ignore values you do not know, new ones can be added.\n\nEvents are not deduplicated: every edit is announced. Use the event `id` to drop repeats.\n","required":["id","event","account","adObject","changes","source","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["campaign.updated"]},"account":{"$ref":"#/components/schemas/WebhookAdsAccount"},"adObject":{"type":"object","required":["level","platformId","platformAdAccountId","name"],"properties":{"level":{"type":"string","enum":["CAMPAIGN"],"description":"Always `CAMPAIGN`."},"platformId":{"type":"string","description":"Platform-native campaign ID, usable as campaignId with /v1/ads/campaigns/{campaignId}."},"platformAdAccountId":{"type":"string","description":"Platform-native ad account ID."},"name":{"type":["string","null"]}}},"changes":{"type":"array","description":"Fields edited by this request. `status` is the campaign's own on/off switch. Ignore values you do not know.","items":{"type":"string","enum":["name","status","budget","bid","schedule","targeting","creative","settings"]}},"source":{"type":"string","enum":["zernio","platform"],"description":"Where the edit was made. `zernio` for edits through Zernio, `platform` for edits the sync detected outside Zernio."},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event."}}},"WebhookPayloadAdReview":{"type":"object","description":"Webhook payload for the `ad.review.approved` and `ad.review.rejected` events. Emitted for every ad network Zernio syncs (Meta, Google, TikTok, LinkedIn, Pinterest, X, Reddit and the rest).\n\nFires when an ad Zernio already tracked changes review outcome:\n\n- `approved`: it leaves review as deliverable, or a rejection is overturned.\n- `rejected`: the platform rejects it.\n\nAds seen for the first time by a sync, including the history loaded when an account is connected, never fire it.\n\nOn X, Pinterest and LinkedIn, Zernio reads the review apart from the delivery status. An ad that leaves review while paused (for example under a paused campaign) still sends `approved`.\n\nOn the other networks the review shows only in the delivery status, so an ad that leaves review paused sends no `approved` event.\n\nDetected by Zernio's own ad sync (and, for Meta, the review poll), so it arrives within one sync cycle of the platform's decision, not instantly. Each outcome is delivered at most once per ad per 24 hours.\n","required":["id","event","account","adObject","review","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["ad.review.approved","ad.review.rejected"]},"account":{"$ref":"#/components/schemas/WebhookAdsAccount"},"adObject":{"type":"object","required":["level","platformId","platformAdAccountId","adId","name"],"properties":{"level":{"type":"string","enum":["AD"],"description":"Always `AD`."},"platformId":{"type":"string","description":"Platform-native ad ID."},"platformAdAccountId":{"type":"string","description":"Platform-native ad account ID."},"adId":{"type":"string","description":"Zernio ad ID, usable with GET /v1/ads/{adId}."},"name":{"type":"string"}}},"review":{"type":"object","required":["status","raw","reasons"],"properties":{"status":{"type":"string","enum":["approved","rejected"]},"raw":{"type":"string","description":"Platform-native status string, forwarded verbatim (Meta `ACTIVE` / `DISAPPROVED`, TikTok `DISABLE`, ...)."},"reasons":{"type":"array","description":"Why the platform rejected the ad, when it says. Always empty on `approved`. Pinterest, LinkedIn and Reddit send their own reasons, X sends none, and most other networks only return a generic message.","items":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}}}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event."}}},"WebhookPayloadAdDeliveryIssue":{"type":"object","description":"Webhook payload for the `ad.delivery_issue` event. Fires when an ad Zernio already tracked moves into the platform's error state:\n\n- Meta `WITH_ISSUES` (payment, policy and account problems)\n- TikTok account punishment or missing balance\n- any platform status Zernio does not recognize yet (check `issue.raw`)\n\nAds seen for the first time by a sync never fire it.\n\nDetected by Zernio's own ad sync, so it arrives within one sync cycle. Each ad fires at most once per 24 hours. On Meta, `ad.status_changed` with `WITH_ISSUES` can also fire for the same problem, straight from Meta's webhook.\n","required":["id","event","account","adObject","issue","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["ad.delivery_issue"]},"account":{"$ref":"#/components/schemas/WebhookAdsAccount"},"adObject":{"type":"object","required":["level","platformId","platformAdAccountId","adId","name"],"properties":{"level":{"type":"string","enum":["AD"],"description":"Always `AD`."},"platformId":{"type":"string","description":"Platform-native ad ID."},"platformAdAccountId":{"type":"string","description":"Platform-native ad account ID."},"adId":{"type":"string","description":"Zernio ad ID, usable with GET /v1/ads/{adId}."},"name":{"type":"string"}}},"issue":{"type":"object","required":["raw","reasons"],"properties":{"raw":{"type":"string","description":"Platform-native status string, forwarded verbatim (Meta `WITH_ISSUES`, TikTok `ADVERTISER_ACCOUNT_PUNISH`, LinkedIn `REMOVED`, ...)."},"reasons":{"type":"array","description":"What the platform says is wrong. Meta reports it per campaign; other networks send no message today, so it is empty there.","items":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}}}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event."}}},"WebhookPayloadCampaignBudgetDepleted":{"type":"object","description":"Webhook payload for the `campaign.budget.depleted` event. Fires when a campaign\nZernio already tracked stops delivering because its budget ran out. TikTok only:\nit is the one network that reports an exhausted budget on the ad. Meta and Google\nkeep such ads `ACTIVE`, so they never fire it.\n\nDetected by Zernio's own ad sync. Each campaign fires at most once per 6 hours, so a\ndaily budget that runs out again the next day is announced again.\n","required":["id","event","account","adObject","budget","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["campaign.budget.depleted"]},"account":{"$ref":"#/components/schemas/WebhookAdsAccount"},"adObject":{"type":"object","required":["level","platformId","platformAdAccountId","name"],"properties":{"level":{"type":"string","enum":["CAMPAIGN"],"description":"Always `CAMPAIGN`."},"platformId":{"type":"string","description":"Platform-native campaign ID."},"platformAdAccountId":{"type":"string","description":"Platform-native ad account ID."},"name":{"type":["string","null"]}}},"budget":{"type":"object","required":["raw"],"properties":{"raw":{"type":"string","description":"Platform-native status string, forwarded verbatim (TikTok `AD_STATUS_CAMPAIGN_EXCEED`)."}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event."}}},"WebhookPayloadAdAccountStatusChanged":{"type":"object","description":"Webhook payload for the `ad_account.status_changed` event. Fires when an ad account Zernio already tracked moves between `active`, `restricted`, `disabled` and `closed`, as read by Zernio's ad account discovery (Meta, Google, TikTok, X).\n\nNever fires for an account seen for the first time, an account not seen in the last 48 hours, or a platform status Zernio does not recognize. Each new status fires at most once per account per 24 hours.\n\n`restricted` means the account exists but cannot run ads normally until something is settled (Meta unpaid balance or risk review, TikTok limits or pending verification, X review).\n","required":["id","event","account","adAccount","status","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["ad_account.status_changed"]},"account":{"$ref":"#/components/schemas/WebhookAdsAccount"},"adAccount":{"type":"object","required":["platformAdAccountId","name"],"properties":{"platformAdAccountId":{"type":"string","description":"Platform-native ad account ID."},"name":{"type":["string","null"]}}},"status":{"type":"object","required":["previous","current","raw"],"properties":{"previous":{"type":"string","enum":["active","restricted","disabled","closed"]},"current":{"type":"string","enum":["active","restricted","disabled","closed"]},"raw":{"type":"string","description":"Platform-native status, forwarded verbatim (Meta `account_status` code such as `2`, Google `SUSPENDED`, TikTok `STATUS_LIMIT`, X `REJECTED`)."}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event."}}},"WebhookPayloadAdRuleTriggered":{"type":"object","description":"Webhook payload for the `ad_rule.triggered` event.\n\nFires when a scheduled run of a rule with a `notify` action finds campaigns, ad sets or ads that meet every condition of the rule.\n\nEach object is announced at most once per rule cooldown, so `objects` lists only the objects the run acted on, never the ones still in cooldown. A run where every matching object is still in cooldown sends nothing.\n\nAn object whose action failed gets no cooldown: the next run retries it and reports it again.\n","required":["id","event","account","rule","run","objects","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["ad_rule.triggered"]},"account":{"$ref":"#/components/schemas/WebhookAdsAccount"},"rule":{"type":"object","required":["id","name","level","platformAdAccountId"],"properties":{"id":{"type":"string","description":"Zernio ad rule ID."},"name":{"type":"string"},"level":{"type":"string","enum":["campaign","adset","ad"],"description":"Whether the rule evaluates campaigns, ad sets or ads."},"platformAdAccountId":{"type":"string","description":"Platform-native ad account ID the rule watches."}}},"run":{"type":"object","required":["id","ranAt","today","timezone","timezoneAssumed","currency"],"properties":{"id":{"type":"string","description":"ID of the rule run that triggered."},"ranAt":{"type":"string","format":"date-time","description":"Scheduled time of the run (UTC)."},"today":{"type":"string","format":"date","description":"The ad account's calendar date (YYYY-MM-DD) the condition windows were resolved against, so `today` and `last_7d` mean the account's days, not UTC days."},"timezone":{"type":"string","description":"IANA timezone used for `today`, for example `Europe/Madrid`."},"timezoneAssumed":{"type":"boolean","description":"True when the ad account has no known timezone and UTC was assumed."},"currency":{"type":["string","null"],"description":"ISO 4217 currency of the ad account, which money metrics (`spend`, `cpc`, `cpm`, `cpa`) and condition values are in. Null when unknown."}}},"objects":{"type":"array","description":"The campaigns, ad sets or ads this run acted on, at the rule's `level`, including those whose action failed. Objects still in cooldown are left out.","items":{"type":"object","required":["platformId","name","platformCampaignId","conditions","actions"],"properties":{"platformId":{"type":"string","description":"Platform-native ID of the campaign or ad set."},"name":{"type":"string","description":"Name on the platform. Falls back to `platformId` when the platform reports none."},"platformCampaignId":{"type":["string","null"],"description":"Platform-native ID of the campaign the object belongs to (on a campaign-level rule, the campaign's own ID). Null when unknown."},"conditions":{"type":"array","description":"Every condition of the rule, with the value the object reached.","items":{"type":"object","required":["metric","window","op","value","actual"],"properties":{"metric":{"type":"string","description":"`spend`, `impressions`, `clicks`, `conversions`, `ctr`, `cpc`, `cpm`, `cpa` or `roas`. New values may be added."},"window":{"type":"string","description":"`today`, `yesterday`, `last_3d`, `last_7d`, `last_14d`, `last_30d`, `this_month`, `last_month` or a custom range, in the account's calendar (see `run.today`). New values may be added."},"op":{"type":"string","description":"`>`, `>=`, `<`, `<=`, or `top` and `bottom` for a rank condition, whose `actual` is the object's position (1 first)."},"value":{"type":"number","description":"The threshold set on the rule."},"actual":{"type":["number","null"],"description":"The object's value for the metric over the window. Null when it cannot be computed, for example a cost per action with no actions."}}}},"actions":{"type":"array","description":"What the rule did to the object. Empty on a rule that only notifies.","items":{"type":"object","required":["type","status","reason","previousDailyBudget","newDailyBudget","previousName","newName","previousBidAmount","newBidAmount","targetMetric","previousTarget","newTarget"],"properties":{"type":{"type":"string","enum":["pause","activate","adjust_budget","adjust_bid","adjust_target","reallocate_budget","duplicate","edit_name"]},"status":{"type":"string","enum":["done","skipped","failed"],"description":"Action result.\n\n- `skipped`: the action could not or need not apply (already paused or active, budget at its limit, a budget that is unknown, not daily or set at another level, no live ads, or a permanent refusal from the platform).\n- `failed`: it errored and will be retried on the next run."},"reason":{"type":["string","null"],"description":"Why the action was skipped or failed, or the platform's message. Null when done.\n\nSkipped: `already_paused`, `already_active`, `at_limit`, `budget_unknown`, `budget_not_daily`, `budget_level_mismatch`, `no_live_ads`, `budget_shared`, `portfolio_bid_strategy`, `unsupported_bid_strategy`, `no_target_cpa`, `no_target_roas`.\n\n`daily_limit_reached`: held back by the action's `maxChangesPerDay`. `ads_allowance_exceeded`: a reactivation or budget increase for a team past its free live-ads allowance.\n\n`reallocation_incomplete` (failed): a receiver left alone because a giver's cut did not apply, tried again next run."},"previousDailyBudget":{"type":["number","null"],"description":"On `adjust_budget`, the daily budget before the change, in the ad account currency. Null otherwise."},"newDailyBudget":{"type":["number","null"],"description":"On `adjust_budget`, the daily budget after the change. Null when nothing changed."},"previousName":{"type":["string","null"],"description":"On `edit_name`, the object's name before the change. Null otherwise."},"newName":{"type":["string","null"],"description":"On `edit_name`, the name after the change. Null when nothing changed."},"previousBidAmount":{"type":["number","null"],"description":"On `adjust_bid`, the cap before the change. Null otherwise."},"newBidAmount":{"type":["number","null"],"description":"On `adjust_bid`, the cap after the change. Null when nothing changed."},"targetMetric":{"type":["string","null"],"enum":["cpa","roas",null],"description":"On `adjust_target`, which target moved. Null otherwise."},"previousTarget":{"type":["number","null"],"description":"On `adjust_target`, the target before the change. Null otherwise."},"newTarget":{"type":["number","null"],"description":"On `adjust_target`, the target after the change. Null when nothing changed."}}}}}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event."}}},"WebhookPayloadAutomationCheckCompleted":{"type":"object","description":"Webhook payload for the `automation.check.completed` event: one scheduled check of an automation finished.\n\nIt fires once per check, whatever the outcome, including checks where nothing matched. Ad rules are the first automations on the engine; `automation.kind` names the product.\n","required":["id","event","automation","accountId","check","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["automation.check.completed"]},"automation":{"$ref":"#/components/schemas/WebhookAutomationRef"},"accountId":{"type":"string","description":"The connected account the automation acts on."},"check":{"type":"object","required":["id","slot","outcome","subjectsEvaluated","actionsCount","error"],"properties":{"id":{"type":"string"},"slot":{"type":"string","format":"date-time","description":"The scheduled time the check ran for."},"outcome":{"type":"string","enum":["triggered","no_match","cooldown","daily_limit","failed"]},"subjectsEvaluated":{"type":"integer","description":"How many objects the check read."},"actionsCount":{"type":"integer","description":"How many actions it recorded."},"error":{"type":["string","null"]}}},"timestamp":{"type":"string","format":"date-time"}}},"WebhookPayloadAutomationAction":{"type":"object","description":"Webhook payload for `automation.action.applied`, `automation.action.failed` and `automation.action.unknown`: one change an automation made or tried.\n\nSent once per action as it settles. A refusal decided before any platform call (no live ads, a budget already at its limit) arrives as `automation.action.failed` with `status: skipped`. An `unknown` action is read back by the next check and sent again with its final status.\n","required":["id","event","automation","accountId","checkId","action","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["automation.action.applied","automation.action.failed","automation.action.unknown"]},"automation":{"$ref":"#/components/schemas/WebhookAutomationRef"},"accountId":{"type":"string","description":"The connected account the automation acts on."},"checkId":{"type":"string","description":"The check that recorded the action."},"action":{"type":"object","required":["id","subjectId","type","status","reason","previous","target","actedAt"],"properties":{"id":{"type":"string"},"subjectId":{"type":"string","description":"The platform's id of the object changed: an ad, ad set or campaign for ad rules."},"type":{"type":"string","description":"`pause`, `activate`, `adjust_budget` or `notify` for ad rules. New values may be added."},"status":{"type":"string","enum":["applied","skipped","failed","unknown"]},"reason":{"type":["string","null"]},"previous":{"type":["object","null"],"additionalProperties":true,"description":"The value before the change, such as `{ \"dailyBudget\": 40 }`."},"target":{"type":["object","null"],"additionalProperties":true,"description":"The value the change sets, such as `{ \"dailyBudget\": 48 }` or `{ \"status\": \"paused\" }`."},"actedAt":{"type":"string","format":"date-time"}}},"timestamp":{"type":"string","format":"date-time"}}},"WebhookPayloadAutomationAlert":{"type":"object","description":"Webhook payload for `automation.alert.opened`, `automation.alert.escalated` and `automation.alert.resolved`: an alert episode of an automation with a lifecycle (an ad rule's `lifecycle`).\n\nSent as soon as the check records the change; a resolve that a pause or reactivation causes is sent once it applies. A streak that never opened sends nothing.\n\nAlerts closed outside a check (the rule turned off, deleted or its `lifecycle` removed between checks, or the daily cleanup) are not announced.\n","required":["id","event","automation","accountId","checkId","alert","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["automation.alert.opened","automation.alert.escalated","automation.alert.resolved"]},"automation":{"$ref":"#/components/schemas/WebhookAutomationRef"},"accountId":{"type":"string","description":"The connected account the automation acts on."},"checkId":{"type":"string","description":"The check that moved the alert."},"alert":{"type":"object","required":["id","subjectId","severity","reason"],"properties":{"id":{"type":"string"},"subjectId":{"type":"string","description":"The platform's id of the object: an ad, ad set or campaign for ad rules."},"severity":{"type":["string","null"],"enum":["warning","critical",null]},"reason":{"type":["string","null"],"enum":["condition_cleared","action_applied","not_evaluated","automation_changed","automation_off",null],"description":"Why it resolved, on `automation.alert.resolved` only."}}},"timestamp":{"type":"string","format":"date-time"}}},"WebhookAutomationRef":{"type":"object","required":["id","kind"],"properties":{"id":{"type":"string","description":"The automation's id: the ad rule id for `ad_rule`."},"kind":{"type":"string","description":"The product the automation belongs to: `ad_rule` today. New values may be added."}}},"WebhookAdsAccount":{"type":"object","description":"The connected ads account the event belongs to.","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":"Ads connection platform (`metaads`, `googleads`, `tiktokads`, `linkedinads`, `pinterestads`, `xads`, ...).","example":"tiktokads"},"username":{"type":"string"},"displayName":{"type":["string","null"]}}},"WebhookPayloadAdStatusChanged":{"type":"object","description":"Webhook payload for the `ad.status_changed` event. Currently emitted\nonly for Meta (`metaads`).\n\nSourced from two Meta `ad_account` webhook fields:\n  - `in_process_ad_objects` - the ad object finished processing and\n    exited `IN_PROCESS`. `status.raw` carries Meta's `status_name`.\n  - `with_issues_ad_objects` - the ad object entered `WITH_ISSUES`.\n    `status.raw` is `WITH_ISSUES` and the `error` block is populated\n    from Meta's `error_code` / `error_summary` / `error_message`.\n\nReview outcomes (an ad leaving `PENDING_REVIEW` for `ACTIVE`,\n`DISAPPROVED` and so on) are also emitted from Zernio's own ad sync,\nso they arrive even when Meta skips the webhook. `status.raw` is Meta's\n`effective_status`. An ad-level outcome is delivered once per status:\nwhichever source sees it first sends it.\n","required":["id","event","account","adObject","status","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"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\nthe bare numeric ID (e.g. `120244894077860689`).\n","example":"120244894077860689"},"platformAdAccountId":{"type":"string","description":"Platform-native ad-account ID. For Meta this uses the `act_<id>`\nshape.\n","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\nthis is `status_name` from `in_process_ad_objects` (e.g.\n`ACTIVE`, `PAUSED`, `PENDING_REVIEW`, `ARCHIVED`, `DELETED`,\n`DISAPPROVED`), or `WITH_ISSUES` when sourced from\n`with_issues_ad_objects`. Not constrained by an `enum`, because Meta\nmay add new values.\n","example":"ACTIVE"}}},"error":{"type":"object","description":"Optional. Present on most `WITH_ISSUES` events, carrying the\nplatform's error diagnostics. May be absent on some `WITH_ISSUES`\nevents (Meta does not always include diagnostics). Always absent\nfor any other `status.raw` value. Always null-check before reading.\n","required":["code"],"properties":{"code":{"type":"string","description":"Platform-native error code, forwarded verbatim. For Meta this\nis `error_code` as a string. Use as the stable discriminator, since\n`summary` and `message` are localized.\n","example":"2643001"},"summary":{"type":"string","description":"Short human-readable summary (Meta `error_summary`). Localized\nto the ad-account owner's Meta locale. Display only, do not\nmatch on it.\n","example":"Ad Processing Error"},"message":{"type":"string","description":"Full human-readable error message (Meta `error_message`).\nLocalized, display only.\n"}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadWhatsAppTemplateStatusUpdated":{"type":"object","description":"Webhook payload for the `whatsapp.template.status_updated` event.\nFired when Meta completes (re)review of a template attached to a\nconnected WABA. Maps Meta's `message_template_status_update` field\nonto our event envelope.\n","required":["id","event","account","template","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"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.\n`PENDING_DELETION` is the 24h-grace state after a delete\nrequest before the template is actually removed.\n"},"reason":{"type":"string","description":"Meta's free-form reason for the transition. `\"NONE\"` on\napproval; an explanation string on rejection.\n"}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadWhatsAppTemplateCategoryUpdated":{"type":"object","description":"Webhook payload for the `whatsapp.template.category_updated` event.\nFired when Meta reclassifies a template's category attached to a\nconnected WABA. Maps Meta's `template_category_update` field onto\nour event envelope.\n","required":["id","event","account","template","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["whatsapp.template.category_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","changeType","category"],"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`)."},"changeType":{"type":"string","enum":["scheduled","applied"],"description":"`scheduled` is Meta's 24h advance notice of an upcoming\nreclassification; `applied` is the change taking effect.\n"},"category":{"type":"string","enum":["UTILITY","MARKETING","AUTHENTICATION"],"description":"The category right now, regardless of changeType."},"previousCategory":{"type":"string","enum":["UTILITY","MARKETING","AUTHENTICATION"],"description":"Present only when changeType is `applied`. The category before this change."},"scheduledCategory":{"type":"string","enum":["UTILITY","MARKETING","AUTHENTICATION"],"description":"Present only when changeType is `scheduled`. The category that will take effect at `effectiveAt`."},"effectiveAt":{"type":"string","format":"date-time","description":"Present only when changeType is `scheduled`. ISO-8601 timestamp when the scheduled category takes effect."}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadWhatsAppAccountNameStatusUpdated":{"type":"object","description":"Webhook payload for the `whatsapp.account.name_status_updated` event, fired when Meta finishes reviewing a WhatsApp display-name change on a connected number. Maps Meta's `phone_number_name_update` WABA webhook field onto our event envelope.\n\nFires only for a review outcome (APPROVED, DECLINED, PENDING_REVIEW). A name applied without review reports `name_status: AVAILABLE_WITHOUT_REVIEW` on the phone node instead; Meta never sends this webhook field for that case.\n","required":["id","event","account","name","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["whatsapp.account.name_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"}}},"name":{"type":"object","required":["status","requestedName","rejectionReason","displayPhoneNumber"],"properties":{"status":{"type":"string","enum":["APPROVED","DECLINED","PENDING_REVIEW"],"description":"Normalized from Meta's `decision` (REJECTED -> DECLINED, DEFERRED -> PENDING_REVIEW; the review is still open on DEFERRED, not a rejection)."},"requestedName":{"type":["string","null"],"description":"The display name Meta reviewed. Null if Meta did not send one."},"rejectionReason":{"type":["string","null"],"description":"Meta's free-form decline reason. Null on approval, or when Meta sends the literal string \"NONE\"."},"displayPhoneNumber":{"type":["string","null"],"description":"The phone number this review is for, as Meta reported it."}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadWhatsAppAccountQualityUpdated":{"type":"object","description":"Webhook payload for `whatsapp.account.quality_updated`. Fired when a connected\nnumber's quality rating or messaging limit tier differs from the value Zernio held.\nTier changes that Meta applies to the whole portfolio fire once per connected number.\n","required":["id","event","account","quality","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["whatsapp.account.quality_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","null"]}}},"quality":{"type":"object","required":["source","metaEvent","qualityRating","previousQualityRating","messagingLimitTier","previousMessagingLimitTier","displayPhoneNumber"],"properties":{"source":{"type":"string","enum":["phone_number_quality_update","business_capability_update"],"description":"The Meta webhook field that reported the change."},"metaEvent":{"type":["string","null"],"description":"Meta's `event` on phone_number_quality_update (for example FLAGGED, UNFLAGGED, UPGRADE, DOWNGRADE, ONBOARDING, THROUGHPUT_UPGRADE). Null on business_capability_update."},"qualityRating":{"type":["string","null"],"description":"Current quality rating (GREEN, YELLOW, RED, UNKNOWN), read live from Meta on FLAGGED/UNFLAGGED."},"previousQualityRating":{"type":["string","null"]},"messagingLimitTier":{"type":["string","null"],"description":"Current messaging limit tier, for example TIER_250, TIER_2K, TIER_10K, TIER_100K, TIER_UNLIMITED."},"previousMessagingLimitTier":{"type":["string","null"]},"displayPhoneNumber":{"type":["string","null"]}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadWhatsAppAccountStatusUpdated":{"type":"object","description":"Webhook payload for `whatsapp.account.status_updated`. Fired when Meta restricts,\nflags a violation on, disables, deletes or reinstates the WhatsApp Business Account.\nThe same status is also exposed on the account as `platformStatus`.\n","required":["id","event","account","status","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["whatsapp.account.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","null"]}}},"status":{"type":"object","required":["status","metaEvent","reason","violationType","restrictions","banState","banDate"],"properties":{"status":{"type":"string","enum":["restricted","active"],"description":"`active` only on a reinstatement (DISABLED_UPDATE with ban state REINSTATE)."},"metaEvent":{"type":"string","description":"Meta `account_update` event: ACCOUNT_RESTRICTION, ACCOUNT_VIOLATION, ACCOUNT_DELETED or DISABLED_UPDATE."},"reason":{"type":["string","null"],"description":"Human-readable summary. Null on reinstatement."},"violationType":{"type":["string","null"],"description":"ACCOUNT_VIOLATION only, for example SCAM, ADULT."},"restrictions":{"type":"array","description":"ACCOUNT_RESTRICTION only. Empty otherwise.","items":{"type":"object","required":["type","expiresAt"],"properties":{"type":{"type":"string","description":"For example RESTRICTED_BIZ_INITIATED_MESSAGING, RESTRICTED_CUSTOMER_INITIATED_MESSAGING, RESTRICTED_ADD_PHONE_NUMBER_ACTION."},"expiresAt":{"type":["string","null"],"description":"When the restriction lifts, as Meta sent it (for example 2026-10-30T13:38:04+0000)."}}}},"banState":{"type":["string","null"],"description":"DISABLED_UPDATE only (for example DISABLE, REINSTATE)."},"banDate":{"type":["string","null"],"description":"DISABLED_UPDATE only, as Meta sent it (for example \"September 23, 2026\")."}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadWhatsAppAccountAlertReceived":{"type":"object","description":"Webhook payload for `whatsapp.account.alert_received`, forwarded from Meta's\n`account_alerts` webhook. Alerts about a specific number go to that number's\naccount; business-level alerts go to every connected number on the WABA.\n","required":["id","event","account","alert","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["whatsapp.account.alert_received"]},"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","null"]}}},"alert":{"type":"object","required":["entityType","entityId","severity","status","type","description"],"properties":{"entityType":{"type":["string","null"],"description":"BUSINESS, PHONE_NUMBER or CURRENT_STATUS_ID."},"entityId":{"type":["string","null"]},"severity":{"type":["string","null"],"description":"CRITICAL, WARNING or INFORMATIONAL."},"status":{"type":["string","null"],"description":"ACTIVE or NONE."},"type":{"type":["string","null"],"description":"For example INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED, INCREASED_CAPABILITIES_ELIGIBILITY_FAILED, INCREASED_CAPABILITIES_ELIGIBILITY_NEED_MORE_INFO, OBA_APPROVED, OBA_REJECTED, PROFILE_PICTURE_LOST."},"description":{"type":["string","null"]}}},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WhatsAppContactIdentity":{"type":"object","required":["phoneNumber","businessScopedUserId","parentBusinessScopedUserId","whatsappUsername"],"properties":{"phoneNumber":{"type":["string","null"],"description":"The user's WhatsApp phone number (wa_id), null when Meta did not send it (a username adopter who hides it)."},"businessScopedUserId":{"type":["string","null"],"description":"Meta business-scoped user id (BSUID), for example `US.13491208655302741918`."},"parentBusinessScopedUserId":{"type":["string","null"],"description":"Parent BSUID, shared across the businesses of one portfolio when Meta sends it."},"whatsappUsername":{"type":["string","null"],"description":"The user's WhatsApp username, when Meta sent one with the change. Null on `previous`."}}},"WebhookPayloadWhatsAppContactIdentityChanged":{"type":"object","description":"Webhook payload for the `whatsapp.contact.identity_changed` event. Fired when\nMeta reports that a WhatsApp user is now known by a different identifier: a\n`system` message of type `user_changed_number`, `user_changed_user_id` or\n`user_identity_changed`, or a `user_id_update` webhook (BSUID regenerated).\nZernio re-keys the inbox conversation and contact channel before firing.\n","required":["id","event","account","reason","previous","current","contactId","conversationId","changedAt","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["whatsapp.contact.identity_changed"]},"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","null"]}}},"reason":{"type":"string","enum":["user_changed_number","user_changed_user_id","user_identity_changed","user_id_update"],"description":"Which Meta signal reported the change. `user_changed_number`: new phone number. `user_changed_user_id` and `user_id_update`: new BSUID."},"previous":{"$ref":"#/components/schemas/WhatsAppContactIdentity"},"current":{"$ref":"#/components/schemas/WhatsAppContactIdentity"},"contactId":{"type":["string","null"],"description":"Zernio contact id matched on the new identity, null when none exists yet."},"conversationId":{"type":["string","null"],"description":"Zernio inbox conversation that was re-keyed, null when there was none."},"changedAt":{"type":"string","format":"date-time","description":"When Meta reported the change."},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}},"example":{"id":"7f1c2d4e-0000-4000-8000-000000000001","event":"whatsapp.contact.identity_changed","account":{"accountId":"6a0000000000000000000001","profileId":"6a0000000000000000000002","platform":"whatsapp","username":"+15550001111","displayName":"Acme"},"reason":"user_changed_number","previous":{"phoneNumber":"18325355831","businessScopedUserId":"US.13491208655302741918","parentBusinessScopedUserId":null,"whatsappUsername":null},"current":{"phoneNumber":"15129984441","businessScopedUserId":"US.13491208655302741918","parentBusinessScopedUserId":null,"whatsappUsername":null},"contactId":"6a0000000000000000000003","conversationId":"6a0000000000000000000004","changedAt":"2026-09-30T12:00:00.000Z","timestamp":"2026-09-30T12:00:01.000Z"}},"ApiChangelogOperationRef":{"type":"object","required":["method","path"],"properties":{"method":{"type":"string","example":"POST"},"path":{"type":"string","example":"/v1/ads/create"},"operationId":{"type":"string","example":"createAd"},"tags":{"type":"array","items":{"type":"string"},"description":"OpenAPI tags of the operation.","example":["Ad Campaigns"]},"xPlatforms":{"type":"array","items":{"type":"string"},"description":"The operation's `x-platforms` list, verbatim.","example":["google"]}}},"ApiChangelogEntry":{"type":"object","description":"One API changelog entry, as shown on https://docs.zernio.com/changelog.","required":["id","type","impact","platforms","title","summary","message","publishedAt","specVersion","url","changes"],"properties":{"id":{"type":"string","description":"Stable entry id; the same entry is never published twice."},"type":{"type":"string","enum":["new_feature","breaking_change","improvement","deprecation","minor"],"description":"When `impact` is set, `breaking_change` means exactly `impact: action_required`."},"impact":{"type":["string","null"],"enum":["none","additive","action_required",null],"description":"What an integrator has to do, computed from the OpenAPI diff rather than the prose. Null on entries published before October 2026.\n\n- `action_required`: an existing call or parser can break (an operation, parameter or field removed, a field newly required, a type narrowed, an enum value removed, or authentication changed).\n- `additive`: only new or looser things; existing integrations keep working.\n- `none`: descriptions or examples only.\n"},"platforms":{"type":"array","items":{"type":"string"},"description":"Platform and area slugs the entry is about. Filter with the `platform` query parameter.\n\n- Platform: `instagram`, `facebook`, `threads`, `tiktok`, `x`, `linkedin`, `youtube`, `pinterest`, `reddit`, `bluesky`, `telegram`, `snapchat`, `whatsapp`, `discord`, `slack`, `google-business`, `imessage`.\n- Ads platform: `meta-ads`, `google-ads`, `tiktok-ads`, `linkedin-ads`, `pinterest-ads`, `x-ads`.\n- Area: `ads`, `publishing`, `inbox`, `telephony`, `commerce`, `analytics`, `webhooks`, `general`.\n","example":["whatsapp","inbox"]},"title":{"type":["string","null"],"description":"The change in a few words, for example `Delete inbox conversations`. Null on older entries."},"summary":{"type":["string","null"],"description":"One or two plain sentences on what changed and why it matters. Null when `title` is."},"message":{"type":"string","description":"The details in Markdown: endpoints, fields and how to use them."},"publishedAt":{"type":"string","format":"date-time"},"specVersion":{"type":["string","null"],"description":"The `info.version` of the OpenAPI spec the entry describes, when known."},"url":{"type":"string","format":"uri","description":"The entry on the docs changelog."},"changes":{"type":"object","description":"Deterministic diff of the OpenAPI spec behind the entry. Empty lists when nothing of that kind changed.","required":["endpoints","schemas"],"properties":{"endpoints":{"type":"object","required":["added","removed","modified"],"properties":{"added":{"type":"array","items":{"$ref":"#/components/schemas/ApiChangelogOperationRef"}},"removed":{"type":"array","items":{"$ref":"#/components/schemas/ApiChangelogOperationRef"}},"modified":{"type":"array","items":{"$ref":"#/components/schemas/ApiChangelogOperationRef"}}}},"schemas":{"type":"object","required":["added","removed","modified"],"properties":{"added":{"type":"array","items":{"type":"string"},"description":"Component schema names."},"removed":{"type":"array","items":{"type":"string"}},"modified":{"type":"array","items":{"type":"string"}}}}}}}},"WebhookPayloadApiChangelogPublished":{"type":"object","required":["id","event","entry","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["api.changelog.published"]},"entry":{"$ref":"#/components/schemas/ApiChangelogEntry"},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."}}},"WebhookPayloadTest":{"type":"object","description":"Webhook payload for test deliveries","required":["id","event","message","timestamp"],"properties":{"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"event":{"type":"string","enum":["webhook.test"]},"message":{"type":"string","description":"Human-readable test message"},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this test event (set once when the payload is built). Test fires are sent synchronously as a single attempt; a later redelivery of this event keeps the original value."}}},"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 (media-level restriction), and LinkedIn (organization pages only, min 300 targeted followers). Ignored on unsupported platforms. Stories (Facebook, Instagram) do not support geo-restriction.\n","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\"].\n","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"],"description":"Optional when the item names a connected file (`fileId`): inferred from the file's MIME type."},"url":{"type":"string","format":"uri","description":"A media item with a null, missing or empty url is dropped, unless it names a connected file with `fileId` + `accountId`."},"fileId":{"type":"string","description":"A file of a connected Google Drive or OneDrive account (see the Files endpoints). Requires `accountId`.\n\nThe file is copied into Zernio media storage when the post is created, and the item is stored as a plain `url`. A folder, an undownloadable file or an unknown id fails the request with a 4xx naming `mediaItems[i].fileId`.\n"},"accountId":{"type":"string","description":"The connected Google or Microsoft account the `fileId` belongs to (must have the `files` area). Required with `fileId`."},"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. Set once per image; the same value is sent to each selected platform.\n\n- Applied on: Instagram (feed images only, not Reels/Stories), Facebook, Threads, X (max 1000 chars), LinkedIn, Bluesky, Pinterest (max 500 chars).\n- Ignored on platforms without alt-text support (TikTok, YouTube, Snapchat, Telegram, Reddit, Google Business Profile, WhatsApp) and on video items where the platform does not accept it.\n"},"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, YouTube videos and Shorts, 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)."},"subtitles":{"type":"array","maxItems":20,"description":"Subtitle (closed caption) files for a video item, in SRT or WebVTT. Each language may appear once per video. Zernio downloads each file when the post is created or updated and converts it to the format each platform requires.\n\nSent to YouTube, Facebook videos, LinkedIn, X and Bluesky; ignored with a warning elsewhere. Per platform:\n\n- YouTube: every track.\n- Facebook: every track, up to 200 KB each.\n- Bluesky: every track, up to 20 KB each after conversion to WebVTT.\n- X: the first track only (one subtitle per video).\n- LinkedIn: the first English track only.\n\nTracks a platform cannot take are skipped and reported in the response warnings.\n\nA file that is unreachable, redirects, exceeds 1 MB, is not valid SRT or WebVTT, or is over a platform limit is rejected with a 400 (code INVALID_SUBTITLES). If a platform rejects a file at publish time, the post still publishes, without subtitles.\n","items":{"$ref":"#/components/schemas/MediaSubtitle"}},"tiktokProcessed":{"type":"boolean","description":"Internal flag indicating the image was resized for TikTok"}}},"MediaSubtitle":{"type":"object","required":["url","language"],"properties":{"url":{"type":"string","format":"uri","description":"Public http(s) URL of an SRT or WebVTT file: your own host, or an upload from POST /v1/media/presign (contentType application/x-subrip or text/vtt). It must serve the file directly, since redirects are refused.","example":"https://media.zernio.com/temp/walkthrough.en.srt"},"language":{"type":"string","description":"BCP-47 language code with a two-letter language, e.g. en, es or pt-BR. Viewers see the track labelled with the language name, e.g. English.","example":"en"}}},"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 and limited to image or video. Kept as a separate schema so the generated SDK model does not collide with MediaItem.\n","required":["type","url"],"properties":{"type":{"type":"string","enum":["image","video"]},"url":{"type":["string","null"],"description":"Direct URL to the media file. Null when the platform withholds it: check mediaStatus before downloading.\n\n- Instagram omits the video file for Reels it flags as containing copyrighted material (its docs name audio as the usual cause). type stays \"video\" while the file is permanently unreachable.\n- LinkedIn videos with no file returned: url falls back to the cover image and the item carries mediaStatus: unavailable.\n"},"thumbnail":{"type":"string","description":"Cover image. Still present when url is null."},"mediaStatus":{"type":"string","enum":["available","unavailable"],"description":"unavailable means the media file could not be retrieved (url is null or, for LinkedIn videos, a cover image standing in for the file). available or absent means the file is available at url (older synced items omit the field)."},"unavailableReason":{"type":"string","enum":["platform_withheld"],"description":"Why the file is missing. platform_withheld means the platform declined to return it and retrying will not help."}}},"MediaContentType":{"type":"string","description":"MIME type of the file to upload. Rejected with a 400 (INVALID_FIELD_VALUE on contentType) when it is not one of these values, so generic types such as application/octet-stream are not accepted here.","example":"video/mp4","enum":["image/jpeg","image/jpg","image/png","image/webp","image/gif","video/mp4","video/mpeg","video/quicktime","video/avi","video/x-msvideo","video/webm","video/x-m4v","application/pdf","audio/mpeg","audio/mp4","audio/aac","audio/ogg","audio/wav","audio/webm","audio/x-m4a","application/x-subrip","text/vtt"]},"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":{"type":"object","additionalProperties":true,"description":"The platform-specific options stored on this target, echoed back as sent.\n\nTyped per platform on the way in (see the *PlatformData schemas on the request body); free-form on the way out. A response is not guaranteed to match exactly one variant, and generated clients that pick a variant by structure reject the entire response when it doesn't.\n\nZernio's internal publishing state (snapshots, container ids, publish stage) is never returned here. The key is omitted rather than sent as an empty object.\n"},"status":{"type":"string","example":"pending","description":"Platform-specific status: pending, processing, uploading, published, failed, cancelled (removed from the platform via POST /v1/posts/{postId}/unpublish)"},"platformPostId":{"type":"string","description":"The native post ID on the platform (populated after successful publish)","example":"1234567890123456789"},"platformPostUrl":{"type":["string","null"],"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.\n\nEmpty when the platform confirmed the publish without returning an id a permalink can be built from (TikTok returns a publish id for some uploads). The TikTok reconcile cron backfills it later. If TikTok never returns one, /v1/analytics reports that entry as syncStatus unavailable.\n","example":"https://twitter.com/acmecorp/status/1234567890123456789"},"publishedAt":{"type":"string","format":"date-time","description":"Timestamp when the post was published to this platform. YouTube uploads a scheduled public video up to 15 minutes early as private with YouTube's own release time, so its entry is published with this set to scheduledFor, the moment the video goes public."},"removedFromPlatformAt":{"type":["string","null"],"format":"date-time","description":"Set when a successfully published post later disappears from the platform (deleted on-platform or taken down by the platform). Absent while the post is live, and cleared if it reappears.\n\nstatus stays \"published\" (it reflects the publish outcome), so poll this field to detect post-publish removals. Detection runs with the analytics sync: expect up to a few hours of lag.\n"},"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.\n\nInstagram's Graph API exposes no readable trial field, so this reflects creation-time intent only: the reel STARTED as a trial, not whether or when it graduated.\n"},"trialGraduationStrategy":{"type":"string","enum":["MANUAL","SS_PERFORMANCE"],"description":"Graduation strategy the trial reel was launched with. Present only when isTrialReel is true."},"publishAttempts":{"type":"integer","description":"Number of times the publishing pipeline claimed this target to publish it since it was created or last manually retried (a manual retry resets it, except on TikTok). Not the number of retries (see publishRetries)."},"publishRetries":{"type":"integer","description":"Instagram only. Automatic re-sends of media_publish on the same container that Zernio scheduled after Meta answered a transient error: 30 min, 2 h and 6 h after each failure, at most 3. Absent when none was scheduled.\n\nWhile the target is still processing, the latest one may not have been sent yet. Not reset by a manual retry. Independent of publishAttempts, which counts publish-leg claims.\n"},"errorMessage":{"type":"string","description":"Human-readable reason this target has not published yet, or why it failed.\n\n- Failed entries: why the publish failed, with the platform's error details.\n- Pending entries: why the publish has not gone out yet, for example the last temporary error while Zernio retries the publish automatically, or a posting limit notice.\n\nA posting limit holds the post with the notice \"This post is queued and will publish automatically after <timestamp>\".\n\nThe limits are the hourly posting velocity limit and, on a TikTok account connected through the TikTok for Business app, the daily cap of 15 videos and 15 photo posts.\n\nA held post keeps status pending and its scheduledFor moves to that timestamp. It is not failed.\n"},"errorCategory":{"type":"string","enum":["auth_expired","user_content","user_abuse","account_issue","platform_rejected","platform_error","platform_rate_limit","quota_exhausted","system_error","unknown"],"description":"Error category for programmatic handling:\n\n- `auth_expired`: token expired/revoked\n- `user_content`: wrong format/too long\n- `user_abuse`: rate limits/spam\n- `account_issue`: config problems\n- `platform_rejected`: policy violation\n- `platform_error`: 5xx/maintenance\n- `platform_rate_limit`: platform throttling, retried automatically\n- `quota_exhausted`: a shared quota pool the integration draws on is empty, including our own capacity gate in front of one. Not caused by your content or account, and safe to retry once the pool frees up.\n- `system_error`: Zernio infra\n- `unknown`\n"},"errorSource":{"type":"string","enum":["user","platform","system"],"description":"Who caused the error: user (fix content/reconnect), platform (outage/API change), system (Zernio issue, rare)"},"platformError":{"$ref":"#/components/schemas/PostPlatformError"}}},"PostPlatformError":{"type":"object","required":["message"],"description":"The platform's own error for this target, so you can see what the platform said (access tokens are redacted). errorMessage stays the human-readable summary; this block is for diagnostics and support tickets.\n\n**Lifecycle**: set when the last attempt failed with an error the platform described (currently Instagram and Facebook). Kept while an automatic retry of that failure is pending or running; cleared when the target publishes or is retried manually.\n\n**Instagram**:\n\n- Media processing failures carry no code or subcode, only Meta's status text in message.\n- On a publish whose outcome is uncertain (for example errorMessage starting \"Instagram did not confirm\"), carries the last media_publish error Meta returned, when it returned one. errorMessage stays the verdict, so do not read this block as a confirmed failure.\n","properties":{"code":{"type":"integer","description":"Meta error code, when Meta sent one."},"subcode":{"type":"integer","description":"Meta error_subcode, when Meta sent one."},"message":{"type":"string","description":"The platform's raw error message or media processing status text."}}},"Post":{"type":"object","properties":{"_id":{"type":"string"},"userId":{"oneOf":[{"type":"string"},{"$ref":"#/components/schemas/User"}]},"title":{"type":"string","description":"Stored on the post for reference/display only. This field is NOT used as the video title when publishing. To set a YouTube video title, use platformSpecificData.title on the youtube platform target (falls back to the first line of content when omitted)."},"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","pending_approval","scheduled","publishing","published","partial","failed","cancelled"],"description":"`cancelled` is set by POST /v1/posts/{postId}/unpublish once every platform entry has been removed from its platform (a post with published entries left becomes `partial`); cancelled posts can be edited and rescheduled like drafts. `pending_approval` (set by `requiresApproval: true`) never publishes until POST /v1/posts/{postId}/review approves it."},"tags":{"type":"array","description":"YouTube constraints: each tag max 100 chars, combined max 500 chars, duplicates removed.","items":{"type":"string"}},"hashtags":{"type":"array","description":"Stored for reference only. Hashtags are NOT automatically appended to the caption when publishing. Include hashtags directly in the content field (platforms like Instagram only support hashtags as caption text). For YouTube keywords, use the tags field instead.","items":{"type":"string"}},"mentions":{"type":"array","description":"Stored for reference only. Publishing does not create mentions from this 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"},"profileId":{"type":"string","description":"Profile the post is filed under. Set only on drafts that have no platforms."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time","description":"Last change to the post or to any of its platforms (a publish, a failure, a resolved URL)."}}},"RecyclingConfig":{"type":"object","description":"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.\n\n- Weekly or monthly intervals.\n- Maximum 10 active recycling posts per account.\n- YouTube and TikTok are excluded.\n- Content variations are recommended for X and Pinterest to avoid duplicate flags.\n","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":"Content variations for recycled copies. Each recycle uses the next variation, in round-robin order. Recommended for X and Pinterest to avoid duplicate content flags.\n\n- If omitted, the original post content is used for all recycled copies.\n- Send an empty array [] to clear existing variations.\n- Must have 2+ entries when setting variations.\n- Platform-level customContent still overrides the base content per platform.\n"}}},"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)"}}},"XArticleTextRange":{"type":"object","additionalProperties":false,"required":["from_index","to_index","text"],"properties":{"from_index":{"type":"integer","minimum":0,"description":"Inclusive start index in the block text."},"to_index":{"type":"integer","minimum":0,"description":"Exclusive end index in the block text. Must be greater than or equal to from_index and no greater than the block text length."},"text":{"type":"string","description":"Text represented by this metadata range."}}},"XArticleInlineStyleRange":{"type":"object","additionalProperties":false,"required":["offset","length","style"],"properties":{"offset":{"type":"integer","minimum":0},"length":{"type":"integer","minimum":0},"style":{"type":"string","enum":["bold","italic","strikethrough"]}},"description":"The offset plus length must not exceed the containing block's text length."},"XArticleEntityRange":{"type":"object","additionalProperties":false,"required":["key","offset","length"],"properties":{"key":{"type":"integer","minimum":0,"description":"Zero-based index into content_state.entities."},"offset":{"type":"integer","minimum":0},"length":{"type":"integer","minimum":0}},"description":"The referenced entity must exist, and offset plus length must not exceed the containing block's text length."},"XArticleBlock":{"type":"object","additionalProperties":false,"required":["type","text"],"properties":{"type":{"type":"string","enum":["unstyled","header-one","header-two","header-three","unordered-list-item","ordered-list-item","blockquote","atomic"]},"text":{"type":"string"},"key":{"type":"string","minLength":1},"data":{"type":"object","additionalProperties":false,"properties":{"cashtags":{"type":"array","items":{"$ref":"#/components/schemas/XArticleTextRange"}},"hashtags":{"type":"array","items":{"$ref":"#/components/schemas/XArticleTextRange"}},"mentions":{"type":"array","items":{"$ref":"#/components/schemas/XArticleTextRange"}},"urls":{"type":"array","items":{"$ref":"#/components/schemas/XArticleTextRange"}}}},"inline_style_ranges":{"type":"array","items":{"$ref":"#/components/schemas/XArticleInlineStyleRange"}},"entity_ranges":{"type":"array","items":{"$ref":"#/components/schemas/XArticleEntityRange"}}}},"XArticleEntity":{"oneOf":[{"type":"object","additionalProperties":false,"required":["key","value"],"properties":{"key":{"type":"string","minLength":1},"value":{"type":"object","additionalProperties":false,"required":["type","mutability","data"],"properties":{"type":{"type":"string","const":"post"},"mutability":{"type":"string","enum":["immutable","mutable","segmented"]},"data":{"type":"object","additionalProperties":false,"required":["post_id"],"properties":{"post_id":{"type":"string","minLength":1}}}}}}},{"type":"object","additionalProperties":false,"required":["key","value"],"properties":{"key":{"type":"string","minLength":1},"value":{"type":"object","additionalProperties":false,"required":["type","mutability","data"],"properties":{"type":{"type":"string","const":"link"},"mutability":{"type":"string","enum":["immutable","mutable","segmented"]},"data":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}}},{"type":"object","additionalProperties":false,"required":["key","value"],"properties":{"key":{"type":"string","minLength":1},"value":{"type":"object","additionalProperties":false,"required":["type","mutability","data"],"properties":{"type":{"type":"string","const":"image"},"mutability":{"type":"string","enum":["immutable","mutable","segmented"]},"data":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri","pattern":"^https?://.+\\.(?:[jJ][pP][eE]?[gG]|[pP][nN][gG]|[wW][eE][bB][pP]|[gG][iI][fF]|[mM][pP]4)(?:[?#].*)?$","description":"Public image, GIF, or MP4 URL. Zernio uploads it to X and replaces it with native media metadata. Caller-supplied media IDs are rejected."},"caption":{"type":"string"},"altText":{"type":"string","maxLength":1000,"description":"Supported for image and GIF URLs; rejected for MP4 media."}}}}}}},{"type":"object","additionalProperties":false,"required":["key","value"],"properties":{"key":{"type":"string","minLength":1},"value":{"type":"object","additionalProperties":false,"required":["type","mutability","data"],"properties":{"type":{"type":"string","const":"emoji"},"mutability":{"type":"string","enum":["immutable","mutable","segmented"]},"data":{"type":"object","additionalProperties":false,"required":["entity_key"],"properties":{"entity_key":{"type":"string","minLength":1}}}}}}},{"type":"object","additionalProperties":false,"required":["key","value"],"properties":{"key":{"type":"string","minLength":1},"value":{"type":"object","additionalProperties":false,"required":["type","mutability","data"],"properties":{"type":{"type":"string","const":"markdown"},"mutability":{"type":"string","enum":["immutable","mutable","segmented"]},"data":{"type":"object","additionalProperties":false,"required":["markdown"],"properties":{"markdown":{"type":"string"}}}}}}},{"type":"object","additionalProperties":false,"required":["key","value"],"properties":{"key":{"type":"string","minLength":1},"value":{"type":"object","additionalProperties":false,"required":["type","mutability","data"],"properties":{"type":{"type":"string","enum":["divider","latex"]},"mutability":{"type":"string","enum":["immutable","mutable","segmented"]},"data":{"type":"object","additionalProperties":false}}}}}],"description":"Entity keys must be unique decimal strings matching their zero-based array index (`\"0\"`, `\"1\"`, ...)."},"XArticleContentState":{"type":"object","additionalProperties":false,"externalDocs":{"description":"Official X Article content format reference","url":"https://docs.x.com/x-api/articles/create-draft-article"},"required":["blocks","entities"],"properties":{"blocks":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/XArticleBlock"}},"entities":{"type":"array","items":{"$ref":"#/components/schemas/XArticleEntity"}}},"description":"X's snake_case content-state shape. Standard DraftJS camelCase fields such as entityMap, inlineStyleRanges, and entityRanges are rejected."},"XArticle":{"type":"object","additionalProperties":false,"required":["title","content_state"],"properties":{"title":{"type":"string","minLength":1},"content_state":{"$ref":"#/components/schemas/XArticleContentState"},"mode":{"type":"string","enum":["publish","draft"],"default":"publish","description":"Publish creates an X Article draft and then publishes it. Draft stops after draft creation and returns the X draft ID without a public URL."},"cover":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri","pattern":"^https?://.+\\.(?:[jJ][pP][eE]?[gG]|[pP][nN][gG]|[wW][eE][bB][pP])(?:[?#].*)?$","description":"Public JPG, JPEG, PNG, or WebP URL. GIF, MP4, AVIF, extensionless URLs, and caller-supplied native media IDs are rejected."},"altText":{"type":"string","maxLength":1000}}}},"description":"Long-form X Article payload. Requires an eligible X Premium+ account.\n\nMutually exclusive with top-level/custom tweet media and with threadItems, poll, quoteTweetId, replyToTweetId, inReplyToTweetId, replySettings, sensitiveMedia, paidPartnership, and madeWithAi.\n\nPublishing normally performs two billable X API requests at $0.010 each (draft + publish, $0.020 total). Mode `draft` performs only the $0.010 draft request.\n\n`articleDraftId` is an internal recovery checkpoint and must not be supplied by API clients.\n"},"TwitterPlatformData":{"type":"object","properties":{"article":{"$ref":"#/components/schemas/XArticle"},"replyToTweetId":{"type":"string","description":"ID of an existing tweet to reply to. The published tweet appears as a reply in that tweet's thread. For threads, only the first tweet replies to the target; subsequent tweets chain normally.\n\nX 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.\n"},"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. For threads, applies to the first tweet only.\n\n- Mutually exclusive with media and poll.\n- X only permits quoting your own posts, or posts you are mentioned in or part of the conversation thread of. Quoting an arbitrary other account's post is rejected by X.\n- 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).\n"},"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].\n","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":"Uploads the video with X's amplify_video media category instead of the standard tweet_video. Applied only when the connected X account has a paid X subscription; on other accounts the flag is accepted and ignored.\n\nIt is not required to post long videos. The standard tweet_video path already publishes videos well past 140 seconds on free accounts, and maximum duration is set by X per account, not by Zernio. Zernio enforces only the 512 MB file-size limit.\n\nSome accounts additionally require X's long-video API allowlisting, without which X rejects an amplify_video upload.\n"},"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."}}},"mediaTaggedUsers":{"type":"array","maxItems":10,"items":{"type":"string","pattern":"^@?\\w{1,15}$"},"description":"X usernames (with or without @) to tag on the photos of the post, up to 10. Photos only, not video or GIF. Applied to the media of every tweet in a thread. An unknown username fails the post."}},"description":"X-specific post options. The article field creates a long-form X Article and is mutually exclusive with tweet media and tweet-only options. Geo-restriction applies at the media level: media is hidden outside the specified countries while tweet text remains visible.\n"},"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."},"firstComment":{"type":"string","maxLength":500,"description":"Optional first comment, posted right after publishing as a reply to the published post. With threadItems, it replies to the root post.\n\nUp to 500 characters (the Threads post limit). The reply is itself a Threads post, so it uses one of the 250 posts a profile may publish per 24 hours.\n"},"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].\n","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."},"isAiGenerated":{"type":"boolean","default":false,"description":"When true, Facebook shows its AI-disclosure label on the post. Forwarded as is_ai_generated on Reels (contentType=reel) and video Stories (contentType=story with a video). Meta documents no such parameter for feed posts, feed videos or photo Stories, so the flag is accepted with a warning and no label there."},"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"},"collaborators":{"type":"array","items":{"type":"string"},"description":"Facebook Page IDs (numeric, up to 10 unique) to invite as collaborators. Reels only (contentType=reel), sent after the Reel is published, never for drafts. Each Page must accept. Meta allows 10 invites per Page per 24 hours; rejected invites are listed in failedCollaborators. Other values are ignored with a warning."},"failedCollaborators":{"type":"array","readOnly":true,"items":{"type":"object","required":["pageId","reason"],"properties":{"pageId":{"type":"string"},"reason":{"type":"string"}}},"description":"Output only. Collaborator invites Facebook rejected after the Reel was published. The Reel itself stays published."},"facebookSettings":{"$ref":"#/components/schemas/FacebookSettings"}},"description":"Facebook post settings.\n\n- Feed posts: up to 10 images (no mixed video+image).\n- Stories: single media (24h, no captions).\n- Reels: a single vertical video (9:16). The Zernio API does not preflight Reel duration; Meta's Reels publishing guide documents 3-90 seconds.\n- Geo-restriction: a hard visibility restriction (users outside the specified countries cannot see the post). Not supported for stories.\n\nDraft, carousel and colored-background text options live under facebookSettings, see FacebookSettings.\n"},"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.\n","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":10,"description":"Renders the post as a multi-link carousel (organic Page post). Mutually exclusive with contentType=story|reel.\n\n- mediaItems must be provided with the same length, and all items must be images (no videos).\n- Each cards[i] adds the click-through link and headline for the image at mediaItems[i].\n- Facebook truncates name at ~35 chars and description at ~30 chars on render; longer strings are accepted.\n","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.\n"},"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.\n\nPages only (ignored on personal profiles and groups), and text-only feed posts only. 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.\n\nLength 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.\n\nA 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.\n"}}},"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). Collaborators are supported on Instagram and Facebook Page Reels only. TikTok, YouTube, Threads, LinkedIn, X and Pinterest do not expose collaborators in their public APIs."},"droppedCollaborators":{"type":"array","readOnly":true,"description":"Output only. Set by Zernio when Instagram rejected these collaborators and the retry was sent without them.","items":{"type":"object","required":["username","reason"],"properties":{"username":{"type":"string","description":"The collaborator username Instagram rejected","example":"brandcommunity"},"reason":{"type":"string","description":"The reason Instagram gave for rejecting the collaborator"}}}},"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:\n\n- Photos: require x/y coordinates. Photo tags without valid coordinates are skipped.\n- Reels and videos: username only (coordinates are ignored).\n- Stories: optional coordinates.\n- Carousels: use mediaIndex to target specific slides (defaults to 0); video slides take username-only tags.\n","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. Unrelated to audioConfiguration, which attaches a catalog track.","example":"My Podcast Intro"},"audioConfiguration":{"type":"object","description":"Attach a licensed music track or original sound from the Instagram audio catalog to a Reel. Reels only (single video post, not a story or image).\n\n- Requires an Instagram account connected via Facebook Login. Classic Instagram Login accounts get a 400 (instagram_audio_requires_facebook_login).\n- Get audio IDs from GET /v1/accounts/{accountId}/instagram/audio.\n- If the track becomes unavailable by publish time (removed, region-blocked, licensing change), the post fails with a user-error. It is not published without the audio.\n","required":["audioId"],"properties":{"audioId":{"type":"string","description":"Audio asset ID from the audio search endpoint.","example":"482851939985510"},"audioVolume":{"type":"integer","minimum":0,"maximum":100,"description":"Volume of the attached audio track, 0-100. Defaults to 100.","example":80},"videoVolume":{"type":"integer","minimum":0,"maximum":100,"description":"Volume of the video's own sound, 0-100. Defaults to 100. Set 0 to mute the original video audio.","example":100}}},"muteAudio":{"type":"boolean","default":false,"description":"Publish the video without sound. Applies to Reels, Stories, and video carousel slides; ignored for images.\n\nInstagram has no mute parameter, so we strip the audio track from the file before handing it to Instagram. The published video is permanently silent, and the original audio cannot be restored from Instagram.\n\n- If the audio cannot be stripped, the post fails rather than publishing with sound.\n- Videos above 200MB cannot be muted at all, so mute them before uploading.\n\nUnrelated to audioConfiguration.videoVolume, which only lowers the original sound when a catalog track is attached.\n","example":true},"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."},"isPaidPartnership":{"type":"boolean","default":false,"description":"When true, Instagram shows the \"Paid partnership\" label on the post. Applies to feed posts, Reels, and carousels; not supported on Stories (400). Requires an Instagram account connected via Facebook Login; classic Instagram Login accounts get a 400 (instagram_paid_partnership_requires_facebook_login). Implied when brandedContentSponsors is set.","example":true},"brandedContentSponsors":{"type":"array","maxItems":2,"items":{"type":"string"},"description":"Up to 2 brands to tag as sponsors, each an Instagram username (leading @ optional) or a numeric Instagram user ID. Sponsors must be professional (Business or Creator) accounts.\n\n- Usernames are resolved at publish time via the Business Discovery API on the publishing account. A sponsor that cannot be resolved (private, personal, or nonexistent account) fails the post with a user error naming it.\n- A brand that has pre-approved the creator shows as \"Paid partnership with @brand\" immediately; otherwise the plain label shows and the brand receives an approval request.\n\nSets isPaidPartnership. Same login and content-type rules as isPaidPartnership.\n","example":["nike","17841400000000000"]},"commentsEnabled":{"type":"boolean","default":true,"description":"When false, comments are turned off on the post right after it is published (Meta's comment_enabled on the media object).\n\n- Applies to feed posts, Reels and carousels; ignored for Stories, which have no comments.\n- Works with both Instagram connection methods.\n- Best-effort: if the toggle fails after a successful publish, the post still succeeds and stays live with comments on.\n","example":false},"locationId":{"type":"string","pattern":"^[0-9]+$","description":"Tags the post with a location: the ID of a Facebook Page that has location data (digits only), sent to Instagram as location_id.\n\n- Applies to feed posts, Reels, and the carousel as a whole.\n- Stories and individual carousel slides are unsupported (a Story with locationId is rejected with a 400).\n- A Page without location data, or that does not exist, fails the post with a user error at publish time.\n","example":"105890561436614"}},"description":"Feed aspect ratio 0.5625-1.91, carousels up to 20 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."},"InstagramMediaCollaborator":{"type":"object","required":["id","username","inviteStatus"],"properties":{"id":{"type":"string","description":"App-scoped ID of the collaborator's Instagram account."},"username":{"type":["string","null"],"description":"Instagram handle of the collaborator."},"inviteStatus":{"type":["string","null"],"description":"accepted or pending. Any other value Meta adds later is passed through in lowercase.","example":"accepted"}}},"InstagramLiveMedia":{"type":"object","required":["id","mediaType","mediaProductType","username","timestamp"],"properties":{"id":{"type":"string","description":"Instagram media ID of the live broadcast."},"mediaType":{"type":["string","null"],"description":"BROADCAST for a live video.","example":"BROADCAST"},"mediaProductType":{"type":["string","null"],"description":"LIVE for a live video.","example":"LIVE"},"username":{"type":["string","null"],"description":"Instagram handle of the broadcasting account."},"timestamp":{"type":["string","null"],"description":"Creation time of the broadcast media as Meta returns it (ISO 8601)."}}},"FacebookVisitorPost":{"type":"object","required":["id","message","createdTime","from","permalinkUrl","media"],"properties":{"id":{"type":"string","description":"Facebook post ID (`{pageId}_{postId}`)."},"message":{"type":["string","null"],"description":"Text of the post. Null for media-only posts."},"createdTime":{"type":["string","null"],"description":"Creation time as Meta returns it (ISO 8601)."},"from":{"type":["object","null"],"description":"The person or Page that published the post. Null when Meta omits the author.","required":["id","name"],"properties":{"id":{"type":"string","description":"App-scoped ID of the author."},"name":{"type":["string","null"]}}},"permalinkUrl":{"type":["string","null"],"description":"Public Facebook URL of the post."},"media":{"type":["object","null"],"description":"Media of the first attachment, in the same shape as Facebook Page posts. Null when the post has no attachment.","required":["mediaType","thumbnailUrl","mediaItems"],"properties":{"mediaType":{"type":"string","enum":["image","video","carousel","text"]},"thumbnailUrl":{"type":"string","description":"Temporary CDN URL of the cover image. Empty when there is none."},"mediaItems":{"type":"array","items":{"type":"object","required":["type","url"],"properties":{"type":{"type":"string","enum":["image","video"]},"url":{"type":"string","description":"Temporary CDN URL."},"thumbnail":{"type":"string","description":"Poster frame of a video."}}}}}}}},"FacebookTaggedPost":{"type":"object","required":["id","message","createdTime","taggedTime","permalinkUrl","pictureUrl","from"],"properties":{"id":{"type":"string","description":"Facebook post ID of the post that tags the Page."},"message":{"type":["string","null"]},"createdTime":{"type":["string","null"],"description":"Publication time as Meta returns it (ISO 8601)."},"taggedTime":{"type":["string","null"],"description":"When the Page was tagged in the post (ISO 8601)."},"permalinkUrl":{"type":["string","null"],"description":"Public Facebook URL of the post."},"pictureUrl":{"type":["string","null"],"description":"Full-size picture attached to the post."},"from":{"type":["object","null"],"description":"Null when Meta does not return the author, which is common for posts by people.","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}}}}},"FacebookPageInfo":{"type":"object","required":["about","description","website","phone","emails","hours"],"properties":{"about":{"type":["string","null"],"description":"Short description, shown as Description in the Page's Edit Page Info."},"description":{"type":["string","null"],"description":"Longer text, shown as Additional Information."},"website":{"type":["string","null"]},"phone":{"type":["string","null"]},"emails":{"type":"array","items":{"type":"string"}},"hours":{"type":"object","description":"Opening hours keyed `{day}_{slot}_{open|close}`, for example `mon_1_open: \"09:00\"`. Empty when the Page has none.","additionalProperties":{"type":"string"}}}},"InstagramTaggedMedia":{"type":"object","required":["id","caption","mediaType","mediaProductType","mediaUrl","thumbnailUrl","permalink","timestamp","username","likeCount","commentsCount"],"properties":{"id":{"type":"string","description":"Instagram media ID of the post the account is tagged in."},"caption":{"type":["string","null"]},"mediaType":{"type":["string","null"],"description":"IMAGE, VIDEO or CAROUSEL_ALBUM.","example":"IMAGE"},"mediaProductType":{"type":["string","null"],"description":"FEED or REELS.","example":"FEED"},"mediaUrl":{"type":["string","null"],"description":"Temporary CDN URL. Meta omits it for videos with copyrighted audio, flagged videos and reels whose owner disabled downloads."},"thumbnailUrl":{"type":["string","null"],"description":"Cover image of a video or reel."},"permalink":{"type":["string","null"],"description":"Public Instagram URL of the post."},"timestamp":{"type":["string","null"],"description":"Publication time as Meta returns it (ISO 8601)."},"username":{"type":["string","null"],"description":"Instagram handle of the account that posted the media and tagged yours."},"likeCount":{"type":["integer","null"],"description":"Null when the owner hides like counts."},"commentsCount":{"type":["integer","null"]}}},"InstagramMentionedMedia":{"type":"object","required":["id","caption","mediaType","mediaUrl","timestamp","username","likeCount","commentsCount"],"properties":{"id":{"type":"string","description":"Instagram media ID of the post whose caption mentions the account."},"caption":{"type":["string","null"]},"mediaType":{"type":["string","null"],"description":"IMAGE, VIDEO or CAROUSEL_ALBUM.","example":"IMAGE"},"mediaUrl":{"type":["string","null"],"description":"Temporary CDN URL. Meta omits it for videos with copyrighted or licensed audio and reels whose owner disabled downloads."},"timestamp":{"type":["string","null"],"description":"Publication time as Meta returns it (ISO 8601)."},"username":{"type":["string","null"],"description":"Instagram handle of the account that posted the media and mentioned yours."},"likeCount":{"type":["integer","null"],"description":"Null when the owner hides like counts."},"commentsCount":{"type":["integer","null"]}}},"InstagramMentionedComment":{"type":"object","required":["id","text","timestamp","likeCount","media"],"properties":{"id":{"type":"string","description":"Instagram comment ID of the comment that mentions the account."},"text":{"type":["string","null"]},"timestamp":{"type":["string","null"],"description":"Creation time as Meta returns it (ISO 8601)."},"likeCount":{"type":["integer","null"]},"media":{"type":["object","null"],"description":"The post the comment was left on.","required":["id"],"properties":{"id":{"type":"string","description":"Instagram media ID of the post."}}}}},"InstagramBusinessDiscovery":{"type":"object","required":["profile","media"],"properties":{"profile":{"type":"object","required":["id","username"],"properties":{"id":{"type":"string","description":"Instagram user ID of the looked-up account"},"username":{"type":"string"},"name":{"type":["string","null"]},"biography":{"type":["string","null"]},"website":{"type":["string","null"]},"profilePictureUrl":{"type":["string","null"],"description":"Temporary CDN URL; download it rather than storing the link."},"followersCount":{"type":["integer","null"]},"followsCount":{"type":["integer","null"]},"mediaCount":{"type":["integer","null"]}}},"media":{"type":"array","description":"Most recent media first, up to `limit`.","items":{"type":"object","required":["id","caption","mediaType","mediaProductType","timestamp","permalink","likeCount","commentsCount","mediaUrl","thumbnailUrl","viewCount","children"],"properties":{"id":{"type":"string"},"caption":{"type":["string","null"]},"mediaType":{"type":["string","null"],"description":"IMAGE, VIDEO or CAROUSEL_ALBUM"},"mediaProductType":{"type":["string","null"],"description":"FEED or REELS"},"timestamp":{"type":["string","null"],"format":"date-time"},"permalink":{"type":["string","null"]},"likeCount":{"type":["integer","null"],"description":"Null when the owner hides like counts"},"commentsCount":{"type":["integer","null"]},"mediaUrl":{"type":["string","null"],"description":"Temporary CDN URL that expires; download the file rather than storing the link. Null on videos whose audio is licensed music, use thumbnailUrl for the cover."},"thumbnailUrl":{"type":["string","null"],"description":"Video cover frame, VIDEO only. Temporary CDN URL."},"viewCount":{"type":["integer","null"],"description":"Reels only. Null on images and carousels."},"children":{"type":["array","null"],"description":"Carousel slides in order. Null unless mediaType is CAROUSEL_ALBUM.","items":{"type":"object","required":["id","mediaType","mediaUrl","thumbnailUrl"],"properties":{"id":{"type":"string"},"mediaType":{"type":["string","null"]},"mediaUrl":{"type":["string","null"]},"thumbnailUrl":{"type":["string","null"]}}}}}}}}},"InstagramAudioAsset":{"type":"object","description":"One asset from the Instagram audio catalog. Licensed music carries artist/artwork fields; original sounds carry creator fields instead, so most fields are nullable.","properties":{"audioId":{"type":"string","description":"Audio asset ID. Pass it as platformSpecificData.audioConfiguration.audioId when creating a Reel.","example":"482851939985510"},"title":{"type":["string","null"],"description":"Track or sound title."},"audioType":{"type":["string","null"],"enum":["music","original_sound",null],"description":"Catalog type of the asset."},"durationInMs":{"type":["integer","null"],"description":"Asset duration in milliseconds."},"displayArtist":{"type":["string","null"],"description":"Artist name (licensed music only)."},"coverArtworkThumbnailUrl":{"type":["string","null"],"description":"Cover artwork thumbnail (licensed music only)."},"downloadUrl":{"type":["string","null"],"description":"Temporary preview URL. Meta expires it after roughly 1.5 days; re-fetch the asset to refresh it."},"igUsername":{"type":["string","null"],"description":"Creator username (original sounds only)."},"profilePictureUrl":{"type":["string","null"],"description":"Creator profile picture (original sounds only)."},"isAdsEligible":{"type":["boolean","null"],"description":"Whether the asset is eligible for ads use."},"onPlatformAudioPreviewLink":{"type":["string","null"],"description":"Instagram web link to preview the audio."}}},"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. Mention with @[https://www.linkedin.com/in/vanity] (resolved to LinkedIn's live name, same rules and errors as post content) or @[Name](urn:li:person|organization:ID); a hand-written name must match LinkedIn's exactly or it renders as plain text."},"disableLinkPreview":{"type":"boolean","description":"Set to true to disable automatic link previews for URLs in the post content (default is false)"},"audience":{"type":"object","description":"Organization pages only (Zernio rejects it on a personal profile). Audience targeting for the post (Ads Manager's \"Targeted audience\"), sent as LinkedIn's distribution.targetEntities: OR inside a facet, AND across facets.\n\nLinkedIn rejects the post when the targeted audience is under 300 members.\n\nURN facets accept a full urn:li:<type>:<id> or the bare numeric id. Find ids with GET /v1/ads/targeting/search?platform=linkedin (types country, region, industry, jobFunction, seniority, companySize).\n","properties":{"countries":{"type":"array","maxItems":25,"items":{"type":"string"},"description":"ISO 3166-1 alpha-2 codes with a built-in LinkedIn geo URN (same list as geoRestriction.countries, merged with it). Other countries and sub-country regions go in geoLocations."},"geoLocations":{"type":"array","items":{"type":"string"},"description":"LinkedIn geo URNs or ids (urn:li:geo:103644278 or 103644278): countries, states, regions, cities."},"interfaceLocales":{"type":"array","items":{"type":"object","required":["language","country"],"properties":{"language":{"type":"string","description":"ISO 639-1, lowercase"},"country":{"type":"string","description":"ISO 3166-1 alpha-2, uppercase"}}},"description":"Members' LinkedIn interface locale, e.g. { language: es, country: ES }."},"industries":{"type":"array","items":{"type":"string"},"description":"urn:li:industry:<id> or id."},"jobFunctions":{"type":"array","items":{"type":"string"},"description":"urn:li:function:<id> or id."},"seniorities":{"type":"array","items":{"type":"string"},"description":"urn:li:seniority:<id> or id."},"staffCountRanges":{"type":"array","items":{"type":"string","enum":["SIZE_1","SIZE_2_TO_10","SIZE_11_TO_50","SIZE_51_TO_200","SIZE_201_TO_500","SIZE_501_TO_1000","SIZE_1001_TO_5000","SIZE_5001_TO_10000","SIZE_10001_OR_MORE"]},"description":"Company size of the member's current employer."},"degrees":{"type":"array","items":{"type":"string"},"description":"urn:li:degree:<id> or id (LinkedIn standardized degrees)."},"fieldsOfStudy":{"type":"array","items":{"type":"string"},"description":"urn:li:fieldOfStudy:<id> or id (LinkedIn standardized fields of study)."},"organizations":{"type":"array","items":{"type":"string"},"description":"Schools, as urn:li:organization:<id> or id (LinkedIn's Organization Lookup)."}}},"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. Mutually exclusive with media. Works on personal profiles and organization pages.\n\nThe published post is always a reshare authored by your account with the original embedded underneath. With content, your text is the commentary (LinkedIn's \"repost with your thoughts\"); with no content it publishes as a text-free reshare.\n\nA text-free reshare is NOT LinkedIn's one-click \"Repost\" (the feed treatment where the original author stays the author). LinkedIn's API exposes no way to create that, so the post still appears authored by you with the original embedded.\n"},"geoRestriction":{"$ref":"#/components/schemas/GeoRestriction"},"poll":{"type":"object","description":"Create a LinkedIn poll with this post. Cannot be combined with media or reshareUrl. Polls cannot be edited after publishing on LinkedIn, and API-created polls are non-sponsored only (they cannot be promoted as ads).","properties":{"question":{"type":"string","minLength":1,"maxLength":140,"description":"Poll question (max 140 characters)"},"options":{"type":"array","minItems":2,"maxItems":4,"items":{"type":"string","minLength":1,"maxLength":30},"description":"Poll options (2-4 choices, max 30 characters each)"},"duration":{"type":"string","enum":["ONE_DAY","THREE_DAYS","SEVEN_DAYS","FOURTEEN_DAYS"],"default":"SEVEN_DAYS","description":"How long the poll accepts votes. Defaults to SEVEN_DAYS."}},"required":["question","options"]}},"description":"LinkedIn post options.\n\n- Media: up to 20 images, no multi-video. A single PDF is supported (max 100MB). Link previews are auto-generated when no media is attached.\n- Use organizationUrn for multi-org posting.\n- Geo-restriction only works for organization pages (not personal profiles) and requires the targeted audience to exceed 300 followers.\n- Polls, via the poll object: 2-4 options, cannot be combined with media or reshareUrl, cannot be edited after publishing. API-created polls are non-sponsored only.\n"},"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\"."}}},"MetaAdsPlatformData":{"type":"object","additionalProperties":false,"description":"Meta (facebook/instagram) options for platformSpecificData on POST /v1/ads/boost and /v1/ads/create. Unknown keys are rejected, not dropped.","properties":{"bidStrategy":{"$ref":"#/components/schemas/BidStrategy"},"bidAmount":{"type":"number","description":"Whole currency units (USD: 5 = $5.00). Required when bidStrategy is LOWEST_COST_WITH_BID_CAP or COST_CAP.\n\nMay also be sent alone, WITHOUT bidStrategy, to set the cap on an ad set joining a COST_CAP / LOWEST_COST_WITH_BID_CAP campaign (the strategy is inherited from the campaign):\n\n- POST /v1/ads/create: that shape requires existingCampaignId and is a 400 otherwise.\n- POST /v1/ads/boost: it is promoted to LOWEST_COST_WITH_BID_CAP."},"roasAverageFloor":{"type":"number","description":"Decimal ROAS multiplier (2.0 = 2.0x). Required when bidStrategy is LOWEST_COST_WITH_MIN_ROAS; sending it without bidStrategy is a 400."},"dailyMinSpendTarget":{"type":"number","description":"Meta daily_min_spend_target on the ad set being created: the least it should spend per day, in whole currency units. A target, not a guarantee.\n\n- It reserves a share of a CAMPAIGN budget, so it requires budgetLevel campaign or an existingCampaignId whose campaign has the budget (Advantage campaign budget / CBO). With an ad-set budget it is a 400 (Meta rejects a spend limit on an ad set that owns its budget).\n- Mutually exclusive with lifetimeMinSpendTarget: the flavour must match the campaign budget type.\n- Rejected with 400 on POST /v1/ads/boost and in adSetId attach mode: use PUT /v1/ads/ad-sets/{adSetId} for an existing ad set."},"lifetimeMinSpendTarget":{"type":"number","description":"Meta lifetime_min_spend_target: the lifetime-budget flavour of dailyMinSpendTarget, in whole currency units. Same rules and same rejections."},"customerLifecycle":{"$ref":"#/components/schemas/MetaCustomerLifecycle"},"adSchedule":{"allOf":[{"$ref":"#/components/schemas/MetaAdSchedule"}],"minItems":1,"description":"Dayparting on the ad set being created (Meta `adset_schedule` with `pacing_type: [\"day_parting\"]`). Change it later with `PUT /v1/ads/ad-sets/{adSetId}`.\n\nA 400 with `param: platformSpecificData.adSchedule` when:\n\n- the budget is daily (on the ad set, or on the campaign joined with `existingCampaignId`): Meta runs a schedule only on a LIFETIME budget.\n- the value is empty.\n- in adSetId attach mode.\n- with `buyingType: RESERVED`.\n"}}},"MetaAdSchedule":{"type":"array","maxItems":168,"description":"Meta ad set dayparting: the hours the ad set delivers, in whole hours.\n\nSame `dayOfWeek` / `startHour` / `endHour` naming as the Google `PUT /v1/ads/campaigns/{campaignId}/ad-schedule`, but Meta has no minutes and no bid modifiers.\n\n- Windows on one day must not overlap (adjacent is fine).\n- Every window must use the same `timezoneType`.\n- Invalid windows are a 400 on `platformSpecificData.adSchedule`.\n","items":{"type":"object","additionalProperties":false,"required":["dayOfWeek","startHour","endHour"],"properties":{"dayOfWeek":{"type":"string","enum":["MONDAY","TUESDAY","WEDNESDAY","THURSDAY","FRIDAY","SATURDAY","SUNDAY"]},"startHour":{"type":"integer","minimum":0,"maximum":23},"endHour":{"type":"integer","minimum":1,"maximum":24,"description":"Must be after startHour. 24 is midnight at the end of the day."},"timezoneType":{"type":"string","enum":["USER","ADVERTISER"],"default":"USER","description":"Meta `timezone_type`: USER runs the hours in each viewer's time zone, ADVERTISER in the ad account time zone."}}}},"MetaCustomerLifecycle":{"type":"object","additionalProperties":false,"required":["strategy"],"description":"Meta's Customer Lifecycle Strategy on a Sales ad set (Meta `ad_set_goal`). Rejected with 400\nin adSetId attach mode: use PUT /v1/ads/ad-sets/{adSetId} for an ad set that already exists.\nRead it back with `GET /v1/ads/ad-sets/{adSetId}?fields=ad_set_goal` (type 0 all customers,\n1 new excluding engaged, 2 new customers).\n","properties":{"strategy":{"type":"string","enum":["all_customers","new_customers","new_customers_excluding_engaged"],"description":"`all_customers` is \"Maximize conversions from all customers\". `new_customers` is \"Acquire new\ncustomers\" (excludes existing customers). `new_customers_excluding_engaged` also excludes\npeople who engaged with you but have not bought yet.\n"},"existingCustomerAudienceIds":{"type":"array","items":{"type":"string"},"description":"Custom audience ids that define your existing customers. Required with both new_customers strategies (Meta answers 400 subcode 1870251 without them); not allowed with all_customers."},"engagedAudienceIds":{"type":"array","items":{"type":"string"},"description":"Custom audience ids of people who engaged but have not bought. Required with new_customers_excluding_engaged, not allowed with the other strategies."}}},"LinkedInAdsPlatformData":{"type":"object","additionalProperties":false,"properties":{"costType":{"type":"string","enum":["CPM","CPC","CPV"],"description":"Campaign cost model (billing event). Defaults to `CPM`. Required when\n`unitCost` is set so the manual bid applies to an explicit cost model.\n"},"unitCost":{"type":"number","description":"Manual bid in WHOLE account-currency units (e.g. 2.5 = $2.50). Requires\n`costType`. Omit for LinkedIn's automated (max delivery) bidding.\nLinkedIn enforces its own per-audience min/max bid bounds.\n"},"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`.\n\n**Default** when omitted, derived from the objective:\n\n- `awareness`: `MAX_IMPRESSION`.\n- `video_views`: `MAX_VIDEO_VIEW`.\n- Every other goal: `MAX_CLICK`. That includes `lead_generation` and `conversions`, because `MAX_LEAD` and `MAX_CONVERSION` need a lead gen form or a conversion rule that neither creation flow attaches.\n\nThe 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.\n\nIt 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.\n"},"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.\nMutually exclusive with the other creative sources.\n","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\ncard; the ad-level `linkUrl` backfills cards that omit it.\n"}}}}}},"document":{"type":"object","additionalProperties":false,"required":["url","title"],"description":"POST /v1/ads/create only. Document ad rendered as an in-feed viewer.\nPDF, PPT or DOC up to 100MB. Mutually exclusive with the other\ncreative sources.\n","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\nviewer's profile photo. Supported goals: traffic, awareness. logoUrl\nand organizationName default to the Company Page's; set them\nexplicitly if LinkedIn rejects the create with a 404. Mutually\nexclusive with the other creative sources.\n","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\nPage. Supported goals: engagement, awareness. headline and\ndescription take exactly one of preApproved or custom. Mutually\nexclusive with the other creative sources.\n","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. Mutually exclusive with the other creative sources.\n\n- Requires goal job_applicants and a Company Page with active job postings.\n- headline and buttonLabel take exactly one of preApproved or custom.\n- logoUrl and organizationName default to the Company Page's.\n","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\nhere; ad-level body and headline are not used. Mutually exclusive\nwith the other creative sources.\n","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.\n\n- Messages are flat nodes wired by local ids. Each button either opens a url or leads to nextMessageId.\n- Cycles, unknown ids and a missing firstMessageId return a 400.\n- LinkedIn does not deliver message ads to EU members.\n- Mutually exclusive with the other creative sources.\n","properties":{"subject":{"type":"string","description":"InMail subject shown in the inbox."},"sender":{"type":"string","description":"Person or organization URN. Defaults to the authoring Company\nPage. The sender must be approved for the ad account first\n(Campaign Manager > Manage message ad senders) or LinkedIn\nrejects the create with SINMAIL_SENDER_NOT_APPROVED.\n"},"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\nheadline needed. Mutually exclusive with the other creative sources.\n","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.\n\nUnlike boostPost, which provisions its own CampaignGroup + Campaign around the post, this attaches the reference under the campaign /v1/ads/create builds, like every other format. You pick bidding / targeting / schedule freely.\n\nNo headline, body, imageUrl or organization are needed; the referenced post carries its own commentary and author. Mutually exclusive with the other creative sources.\n\nPosts from personal profiles (Thought Leader Ads) are NOT supported (see postUrn).\n","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.\n\nGet it via \"Copy link to post\" on the target LinkedIn post. The URL contains -share- (share) or -ugcPost- (ugcPost), then the numeric id.\n\nThe 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 post type.\n\nThis is a LinkedIn limitation (Campaign Manager creates those through a private API). Referencing a member post returns a 422 with a clear error.\n"}}}},"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.\n"},"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."},"boardSectionId":{"type":"string","description":"Target section inside the board. Optional; the pin lands on the board itself when omitted. Pinterest rejects the pin if the section does not belong to boardId, so send both together."},"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"},"isAiGenerated":{"type":"boolean","default":false,"description":"When true, the Pin is created with Pinterest's AI_MODIFIED disclosure (ai_disclosures), which shows an \"AI modified\" label. Applies to image and video Pins. Pinterest offers no \"not AI\" value, so false omits the disclosure. Pinterest may still label a Pin on its own detection."}}},"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."},"notifySubscribers":{"type":"boolean","default":true,"description":"Set false to skip notifying subscribers about this upload (YouTube's notifySubscribers). Defaults to true."},"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."},"defaultLanguage":{"type":"string","description":"Language of the title and description (BCP-47, e.g. ko)."},"defaultAudioLanguage":{"type":"string","description":"Spoken language of the video (BCP-47, e.g. ko). When a video has no audio language, YouTube may set en-US once its metadata is updated."}},"description":"YouTube video settings.\n\n- YouTube publishes a vertical or square video of 3 minutes or less as a Short; there is no flag.\n- Custom thumbnails work on regular videos and Shorts (verified on a Short on 2026-11-01).\n- Scheduled videos are uploaded immediately with the specified visibility.\n- There is no description field here: the description comes from the post content, or from customContent on this platform target when set, truncated to 5000 characters.\n"},"GoogleBusinessPlatformData":{"type":"object","properties":{"locationId":{"type":"string","description":"Target Google Business Profile 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 Google Business Profile, 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.\nprivacyLevel must match creator_info options. Both camelCase and snake_case accepted.\n\nCreator Inbox (draft mode): Set draft: true to send content to the TikTok Creator Inbox\ninstead of publishing immediately. The creator receives an inbox notification and completes\nthe post using TikTok's editing flow. This maps to TikTok's post_mode: \"MEDIA_UPLOAD\" internally.\n\nImportant: The field publish_type is NOT supported. Use draft: true for Creator Inbox flow.\n\nPhoto drafts use the /v2/post/publish/content/init/ endpoint with post_mode: \"MEDIA_UPLOAD\".\nVideo drafts use the dedicated /v2/post/publish/inbox/video/init/ endpoint.\n\nWhen draft: true, the video.upload scope is required. When draft is false or omitted\n(direct post), the video.publish scope is required. For Creator Inbox, TikTok app version\nmust be 31.8 or higher.\n","properties":{"draft":{"type":"boolean","description":"When true, sends the post to the TikTok Creator Inbox as a draft instead of publishing immediately. The creator gets an inbox notification to complete posting via TikTok's editing flow.\n\n- true: maps to TikTok API post_mode: \"MEDIA_UPLOAD\" (photos) or the dedicated inbox endpoint (videos).\n- false or omitted: publishes directly via post_mode: \"DIRECT_POST\".\n\npublish_type is not a supported field; use this field instead.\n"},"privacyLevel":{"type":"string","description":"One of the values returned by the TikTok creator info API for the account. Accounts connected through the TikTok for Business app publish videos as public only: a non-public value on a video post is rejected at creation unless draft is true (photo posts keep every level)."},"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\"\n(\"Your Brand\") implies isBrandOrganicPost and \"brand_content\" (\"Branded Content\",\npaid partnership) implies brandPartnerPromote, so you don't need to send the\nboolean flags separately. Branded content cannot be posted with privacyLevel\nSELF_ONLY.\n"},"brandPartnerPromote":{"type":"boolean","description":"Whether the post promotes a brand partner (branded content / paid partnership).\nOnly needed to disclose BOTH types at once (set it alongside\ncommercialContentType \"brand_organic\"), or to override the value implied by\ncommercialContentType.\n"},"isBrandOrganicPost":{"type":"boolean","description":"Whether the post promotes the creator's own brand (brand organic). Only needed\nto disclose BOTH types at once (set it alongside commercialContentType\n\"brand_content\"), or to override the value implied by commercialContentType.\n"},"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). Any downloadable URL works: we rehost it ourselves. Overrides videoCoverTimestampMs when provided.\n\nThe image is stitched as a single frame at the start of the video to serve as the cover. Accounts connected through the TikTok for Business app instead hand it to TikTok as the cover, with no stitching, falling back to videoCoverTimestampMs without it.\n"},"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). With the brand-organic or branded-content toggle on, TikTok allows Commercial Music Library tracks only, so this attaches nothing there; use musicSoundInfo instead."},"musicSoundInfo":{"type":"object","description":"Commercial Music Library track to attach. Accounts connected through the TikTok for Business app only: a developer-app account rejects the post at publish time with a message that says so. Pick musicSoundId from GET /v1/accounts/{accountId}/tiktok/commercial-music. Ignored on drafts, where TikTok ignores every post_info field.","required":["musicSoundId"],"properties":{"musicSoundId":{"type":"string","description":"The clip.id of a track from GET /v1/accounts/{accountId}/tiktok/commercial-music (its id publishes too, but viewers may see the sound as unavailable in their country; observed from Germany). TikTok fails the publish with a generic 51065 when given the commercial music id instead."},"musicSoundVolume":{"type":"integer","minimum":0,"maximum":100,"default":50,"description":"Track volume. TikTok defaults an omitted volume to 0, which publishes the track silently, so we default to the app's 50. Video posts only."},"musicSoundStart":{"type":"integer","minimum":0,"description":"Start point of the track in milliseconds (default 0). Video posts only."},"musicSoundEnd":{"type":"integer","minimum":0,"description":"End point of the track in milliseconds (default: the video length). Must be greater than musicSoundStart. Video posts only."}}},"videoOriginalSoundVolume":{"type":"integer","minimum":0,"maximum":100,"description":"Volume of the video's own sound when a commercial track is attached (0 to 100). Requires musicSoundInfo. Video posts only. Omitted, TikTok keeps its API default of 0 and the video's own audio is muted under the track (the TikTok app uses 50)."},"videoMadeWithAi":{"type":"boolean","description":"Set true to disclose AI-generated content.\n\nAccounts connected through the TikTok for Business app carry the disclosure on video posts only. The business photo endpoint has no AI disclosure field, so true on a direct photo post is rejected at creation rather than published undisclosed.\n\nTo publish such a photo post, send draft true and set the disclosure in the TikTok app.\n"},"locationId":{"type":"string","description":"Location tag to attach, as the id of a result from GET /v1/accounts/{accountId}/tiktok/locations. Requires locationName. Ignored on drafts, where TikTok ignores every post_info field.\n\nAccounts connected through the TikTok for Business app and video posts only:\n\n- A developer-app account rejects the post at publish time with a message that says so.\n- A direct photo post is rejected at creation, since the business photo endpoint has no location field.\n"},"locationName":{"type":"string","description":"Display name of the location tag, as returned next to its id. Required with locationId; a locationId without it is rejected at creation."},"isAdsOnly":{"type":"boolean","description":"Set true to publish the video as an \"Only show in ads\" post: it is kept off the profile and exists to be used as a Spark Ad. Accounts connected through the TikTok for Business app and video posts only, with the same rejections as locationId. Ignored on drafts."},"description":{"type":"string","maxLength":4000,"description":"Optional long-form caption for photo posts (max 4000 chars). Recommended when content exceeds 90 chars, as photo titles are auto-truncated. Falls back to the post content when omitted."}}},"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-only self post and skips native media uploads, even when media is provided. For native video with body text, omit forceSelf and supply content plus a video mediaItem."},"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 explicitly publish an external link instead.\n\nThe post content (or Reddit customContent override) is included as Markdown body text on the native video.\n\nWhen body text is present, upload failures or subreddit video restrictions fail the post without falling back to a link. Automatic link fallback applies only without body text.\n","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":{"langs":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"string"},"example":["pt","en"],"description":"Language(s) of the post text as 1-3 BCP-47 codes (e.g. \"pt\", \"en-US\"), written to the post record's langs field. Bluesky feed generators filter on it, so posts without it never appear in language-scoped feeds.\n\n- Can only be set at creation (Bluesky has no post editing).\n- With threadItems, every item in the thread carries the same langs.\n- When omitted, the account's default (set via PATCH /v1/accounts/{accountId}/bluesky-settings) applies. With no default either, the field is absent from the record.\n"},"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].\n","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. Use langs to tag post language for feed-generator filtering.\n"},"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.\n\n- Content: plain text (2,000 chars), rich embeds (up to 10), native polls, forum posts, threads, and announcement crossposts.\n- Media: images (JPEG, PNG, GIF, WebP), videos (MP4), and documents (up to 10 files, 25 MB each).\n- Webhook identity (username + avatar): customize per account via PATCH /v1/connect/discord, or per post via webhookUsername/webhookAvatarUrl.\n"},"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. Up to 10 media files per post are uploaded via Slack's file API (the text becomes the caption).\n\nThe channel is chosen at connect time (one connected account per channel), so channelId is NOT accepted here (400). Connect the desired channel via /v1/connect/slack and target its accountId.\n\nMessages over 4,000 characters cannot be edited later (Slack's edit limit is stricter than its post limit).\n"},"DiscordScheduledEvent":{"type":"object","description":"Discord guild scheduled event. Returned by /v1/discord/guilds/{guildId}/events endpoints.\nFields below are the subset Zernio consumes. Discord may return more (e.g. creator,\nimage hash) which we pass through verbatim.\n","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"},"timezone":{"type":["string","null"],"description":"IANA timezone new posts on this profile use when the request names no `timezone`. Null means UTC."},"externalId":{"type":["string","null"],"description":"Your own identifier for this profile, set on create or update. Null when none is set."},"isDefault":{"type":"boolean"},"isOverLimit":{"type":"boolean","description":"Only present when includeOverLimit=true. Indicates if this profile exceeds the plan limit."},"accountCount":{"type":"integer","description":"In the profile list. Connected accounts on the profile, including ones that need reconnecting; phone and SMS number internals and posting accounts hidden by an ads connect are not counted."},"createdAt":{"type":"string","format":"date-time"}}},"EmailAddress":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"name":{"type":["string","null"]}}},"CursorPagination":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"],"description":"Opaque; pass it back as `cursor`."}}},"EmailListMeta":{"type":"object","properties":{"filteredClientSide":{"type":"array","items":{"type":"string"},"description":"The filters the provider could not apply server-side, so they were applied to the fetched page (Microsoft: `bcc`, `anyEmail`, and every other filter when `searchQueryNative` is set)."}}},"EmailAttachment":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string"},"contentType":{"type":"string"},"size":{"type":"integer"},"isInline":{"type":"boolean"},"contentId":{"type":["string","null"]}}},"EmailMessage":{"type":"object","properties":{"id":{"type":"string","description":"The provider's message id."},"threadId":{"type":"string"},"accountId":{"type":"string"},"provider":{"type":"string","enum":["google","microsoft"]},"folders":{"type":"array","items":{"type":"string"}},"from":{"oneOf":[{"$ref":"#/components/schemas/EmailAddress"},{"type":"null"}]},"to":{"type":"array","items":{"$ref":"#/components/schemas/EmailAddress"}},"cc":{"type":"array","items":{"$ref":"#/components/schemas/EmailAddress"}},"bcc":{"type":"array","items":{"$ref":"#/components/schemas/EmailAddress"}},"replyTo":{"type":"array","items":{"$ref":"#/components/schemas/EmailAddress"}},"subject":{"type":"string"},"snippet":{"type":"string"},"text":{"type":["string","null"]},"html":{"type":["string","null"]},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/EmailAttachment"}},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Only with `includeHeaders=true`."},"raw":{"type":"string","description":"MIME source, only with `raw=true`."},"date":{"type":"string","format":"date-time"},"unread":{"type":"boolean"},"starred":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"EmailThread":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"provider":{"type":"string","enum":["google","microsoft"]},"subject":{"type":"string"},"snippet":{"type":"string"},"participants":{"type":"array","items":{"$ref":"#/components/schemas/EmailAddress"}},"messageIds":{"type":"array","items":{"type":"string"}},"draftIds":{"type":"array","items":{"type":"string"}},"folders":{"type":"array","items":{"type":"string"}},"hasAttachments":{"type":"boolean"},"hasDrafts":{"type":"boolean"},"unread":{"type":"boolean"},"starred":{"type":"boolean"},"earliestMessageAt":{"type":["string","null"],"format":"date-time"},"latestMessageReceivedAt":{"type":["string","null"],"format":"date-time"},"latestMessageSentAt":{"type":["string","null"],"format":"date-time"}}},"EmailFolder":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"provider":{"type":"string","enum":["google","microsoft"]},"name":{"type":"string"},"wellKnown":{"type":"string","enum":["inbox","sent","drafts","trash","spam","archive"]},"unreadCount":{"type":"integer"},"totalCount":{"type":"integer"}}},"EmailMessagePatch":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string"},"unread":{"type":"boolean"},"starred":{"type":"boolean"},"folder":{"type":"string","description":"Well-known folder name or folder id to move into."}}},"SendEmailRequest":{"type":"object","required":["accountId","to","subject"],"properties":{"accountId":{"type":"string"},"to":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/EmailAddress"}},"cc":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/EmailAddress"}},"bcc":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/EmailAddress"}},"replyTo":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/EmailAddress"}},"fromName":{"type":"string","maxLength":200},"subject":{"type":"string","maxLength":998},"text":{"type":"string","description":"Plain-text body. One of `text` or `html` is required."},"html":{"type":"string"},"attachments":{"type":"array","maxItems":20,"items":{"type":"object","required":["filename","contentType"],"properties":{"filename":{"type":"string"},"contentType":{"type":"string"},"url":{"type":"string","format":"uri","description":"Fetched at send time. Exactly one of `url` or `base64`."},"base64":{"type":"string"},"contentId":{"type":"string","description":"Makes the attachment inline (`cid:` reference in the html)."}}},"description":"25 MB in total; 3 MB per attachment on Microsoft."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Custom `X-` headers only. `List-Unsubscribe` is dropped on Microsoft and reported in `metadata.droppedHeaders`."},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"scheduledFor":{"type":"string","format":"date-time","description":"Reserved; currently rejected."},"holdAsDraft":{"type":"boolean","description":"Reserved; currently rejected."},"trackOpens":{"type":"boolean","description":"Not available; must be false."},"trackLinks":{"type":"boolean","description":"Not available; must be false."}}},"Calendar":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"provider":{"type":"string","enum":["google","microsoft"]},"name":{"type":"string"},"primary":{"type":"boolean"},"timezone":{"type":["string","null"]},"color":{"type":["string","null"]},"readOnly":{"type":"boolean"}}},"CalendarEventFields":{"type":"object","properties":{"title":{"type":"string","maxLength":1000},"description":{"type":"string","description":"HTML."},"location":{"type":"string"},"start":{"type":"string","description":"ISO date-time, or a date (`YYYY-MM-DD`) for all-day events."},"end":{"type":"string","description":"Exclusive for all-day events."},"allDay":{"type":"boolean"},"timezone":{"type":"string","description":"IANA zone the event is scheduled in. Default UTC."},"participants":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/EmailAddress"}},"recurrence":{"type":"array","maxItems":5,"items":{"type":"string"},"description":"RRULE lines, e.g. `RRULE:FREQ=WEEKLY;BYDAY=MO,WE;COUNT=10`."},"reminders":{"type":"object","properties":{"useDefault":{"type":"boolean"},"overrides":{"type":"array","maxItems":5,"items":{"type":"object","properties":{"minutes":{"type":"integer"}}}}}},"conferencing":{"type":"string","enum":["google_meet","teams"]},"busy":{"type":"boolean"},"visibility":{"type":"string","enum":["default","public","private"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"CreateCalendarEventRequest":{"allOf":[{"type":"object","required":["accountId","title","start","end"],"properties":{"accountId":{"type":"string"},"calendarId":{"type":"string","description":"Defaults to the primary calendar."}}},{"$ref":"#/components/schemas/CalendarEventFields"}]},"CalendarEvent":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"provider":{"type":"string","enum":["google","microsoft"]},"calendarId":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"location":{"type":["string","null"]},"start":{"type":"string","description":"ISO date-time with the rendered offset, or a date for all-day events."},"end":{"type":"string"},"allDay":{"type":"boolean"},"timezone":{"type":["string","null"]},"participants":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/EmailAddress"},{"type":"object","properties":{"status":{"type":"string","enum":["accepted","declined","tentative","pending"]},"comment":{"type":["string","null"]}}}]}},"organizer":{"oneOf":[{"$ref":"#/components/schemas/EmailAddress"},{"type":"null"}]},"recurrence":{"type":["array","null"],"items":{"type":"string"}},"reminders":{"type":"object","properties":{"useDefault":{"type":"boolean"},"overrides":{"type":"array","items":{"type":"object","properties":{"minutes":{"type":"integer"}}}}}},"conferencing":{"type":["object","null"],"properties":{"provider":{"type":"string","enum":["google_meet","teams","other"]},"url":{"type":"string","format":"uri"}}},"busy":{"type":"boolean"},"visibility":{"type":"string","enum":["default","public","private"]},"status":{"type":"string","enum":["confirmed","tentative","cancelled"]},"icalUid":{"type":["string","null"]},"masterEventId":{"type":["string","null"]},"htmlLink":{"type":["string","null"]},"readOnly":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}}},"BusyBlock":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"OpenHours":{"type":"array","items":{"type":"object","required":["days","timezone","start","end"],"properties":{"days":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"description":"0 = Sunday."},"timezone":{"type":"string"},"start":{"type":"string","example":"09:00"},"end":{"type":"string","example":"17:00"},"exdates":{"type":"array","items":{"type":"string","format":"date"},"description":"Dates to exclude."}}}},"WebhookPayloadAccountRateLimited":{"type":"object","description":"Webhook payload for account.rate_limited: a mailbox entered a sending cooldown.","required":["id","event","account","timestamp"],"properties":{"id":{"type":"string"},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["account.rate_limited"]},"account":{"type":"object","required":["accountId","profileId","platform","username","reason","cooldownMinutes","resetsAt"],"properties":{"accountId":{"type":"string"},"profileId":{"type":"string"},"platform":{"type":"string"},"username":{"type":"string"},"displayName":{"type":["string","null"]},"reason":{"type":"string","enum":["recipient_burst","provider_rejection","bounces","daily_cap"]},"cooldownMinutes":{"type":"integer"},"resetsAt":{"type":"string","format":"date-time"}}},"timestamp":{"type":"string","format":"date-time"}}},"WebhookPayloadCalendarEvent":{"type":"object","description":"Webhook payload for calendar.event.created, calendar.event.updated and calendar.event.deleted. Carries the provider event id and the change only; read the event with `GET /v1/calendar/events/{id}` (deleted ids answer 404).","required":["id","event","account","calendarEvent","timestamp"],"properties":{"id":{"type":"string"},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["calendar.event.created","calendar.event.updated","calendar.event.deleted"]},"account":{"type":"object","properties":{"accountId":{"type":"string"},"profileId":{"type":"string"},"platform":{"type":"string"},"username":{"type":"string"},"displayName":{"type":["string","null"]}}},"calendarEvent":{"type":"object","properties":{"id":{"type":"string"},"changeType":{"type":"string","enum":["created","updated","deleted"]}}},"timestamp":{"type":"string","format":"date-time"}}},"FileItem":{"type":"object","description":"A file or folder in a connected Google Drive or OneDrive. Ids are the provider's own.","required":["id","accountId","provider","name","kind","mimeType","size","parentId","webUrl","downloadable","createdAt","modifiedAt","trashed"],"properties":{"id":{"type":"string"},"accountId":{"type":"string"},"provider":{"type":"string","enum":["google","microsoft"]},"name":{"type":"string"},"kind":{"type":"string","enum":["file","folder"]},"mimeType":{"type":["string","null"]},"size":{"type":["integer","null"],"description":"Bytes; null for folders and Google editors files."},"parentId":{"type":["string","null"]},"webUrl":{"type":["string","null"],"description":"The provider's own link to open the item."},"downloadable":{"type":"boolean","description":"False for folders and for Drive files whose owner disabled downloading."},"exportMimeType":{"type":["string","null"],"description":"Google Docs, Slides and Drawings download as PDF/PNG and Sheets as XLSX; this is the type the download carries."},"createdAt":{"type":["string","null"],"format":"date-time"},"modifiedAt":{"type":["string","null"],"format":"date-time"},"trashed":{"type":"boolean"}}},"FileShareLink":{"type":"object","required":["url","scope"],"properties":{"url":{"type":"string","format":"uri"},"scope":{"type":"string","enum":["anyone_with_link"]}}},"WebhookPayloadFilePicked":{"type":"object","description":"Webhook payload for file.picked: the user picked files on a hosted picker page (`POST /v1/files/picker-sessions`), so the app may now open them. Every id was checked against Drive before the event fired.","required":["id","event","account","picker","timestamp"],"properties":{"id":{"type":"string"},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["file.picked"]},"account":{"type":"object","properties":{"accountId":{"type":"string"},"profileId":{"type":"string"},"platform":{"type":"string"},"username":{"type":"string"},"displayName":{"type":["string","null"]}}},"picker":{"type":"object","properties":{"sessionId":{"type":"string","description":"The `id` returned when the session was created."},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"mimeType":{"type":["string","null"]},"kind":{"type":"string","enum":["file","folder"]}}}}}},"timestamp":{"type":"string","format":"date-time"}}},"FilePickerSession":{"type":"object","required":["id","url","expiresAt"],"properties":{"id":{"type":"string","example":"ps_3f2a9c0d1e7b4a6c8d9e0f1a","description":"Public session id, echoed as `pickerSessionId` on the redirect and as `picker.sessionId` on the webhook."},"url":{"type":"string","format":"uri","description":"The hosted picker page. Open it in the end user's browser (redirect or new tab, not an iframe). It is a credential: single-use and valid until `expiresAt`."},"expiresAt":{"type":"string","format":"date-time","description":"30 minutes after creation."}}},"WebhookPayloadFile":{"type":"object","description":"Webhook payload for file.created, file.updated and file.deleted. Carries the provider file id and the change only; read the file with `GET /v1/files/{id}`.","required":["id","event","account","file","timestamp"],"properties":{"id":{"type":"string"},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["file.created","file.updated","file.deleted"]},"account":{"type":"object","properties":{"accountId":{"type":"string"},"profileId":{"type":"string"},"platform":{"type":"string"},"username":{"type":"string"},"displayName":{"type":["string","null"]}}},"file":{"type":"object","properties":{"id":{"type":"string"},"changeType":{"type":"string","enum":["created","updated","deleted"]}}},"timestamp":{"type":"string","format":"date-time"}}},"WebhookPayloadContact":{"type":"object","description":"Webhook payload for contact.updated and contact.deleted, fired after a provider contacts sync (Google Contacts, Outlook) changed a contact. contact.updated also fires after a WhatsApp coexistence address-book change (WhatsApp never fires contact.deleted). Read the contact with `GET /v1/contacts/{id}`.","required":["id","event","account","contact","timestamp"],"properties":{"id":{"type":"string"},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"event":{"type":"string","enum":["contact.updated","contact.deleted"]},"account":{"type":"object","properties":{"accountId":{"type":"string"},"profileId":{"type":"string"},"platform":{"type":"string"},"username":{"type":"string"},"displayName":{"type":["string","null"]}}},"contact":{"type":"object","properties":{"id":{"type":"string"},"changeType":{"type":"string","enum":["updated","deleted"]}}},"timestamp":{"type":"string","format":"date-time"}}},"HubSpotSettings":{"type":"object","required":["_id","platform","hubId","hubDomain","scopes","syncContacts","logMessages","reportDeals","useDealsAsResults"],"properties":{"_id":{"type":"string","description":"Zernio account ID of the HubSpot connection."},"platform":{"type":"string","enum":["hubspot"]},"hubId":{"type":"string","description":"HubSpot portal (hub) ID."},"hubDomain":{"type":["string","null"],"description":"HubSpot portal domain, when HubSpot reports one."},"scopes":{"type":"array","items":{"type":"string"},"description":"OAuth scopes the portal granted."},"syncContacts":{"type":"boolean","description":"Whether Zernio creates HubSpot contacts for inbox contacts that match none."},"logMessages":{"type":"boolean","description":"Whether Zernio logs inbox messages on HubSpot contact timelines."},"reportDeals":{"type":"boolean","description":"Whether Zernio sends closed-won deals as Purchase events to the profile's event destinations."},"useDealsAsResults":{"type":"boolean","description":"Whether closed-won deals count as sales on the ad campaign that brought their contact, in campaign results and ad rules."}}},"GoogleAnalyticsReport":{"type":"object","description":"Google Analytics Data API report, passed through as Google returns it. Every value in `rows` is a string; read `metricHeaders[].type` to parse metrics.","properties":{"accountId":{"type":"string","description":"Zernio account ID of the Google Analytics connection."},"propertyId":{"type":"string","description":"Numeric GA4 property ID."},"dimensionHeaders":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"}}}},"metricHeaders":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","description":"Google metric type, e.g. TYPE_INTEGER, TYPE_FLOAT, TYPE_SECONDS, TYPE_CURRENCY."}}}},"rows":{"type":"array","items":{"type":"object","properties":{"dimensionValues":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"}}}},"metricValues":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"}}}}}}},"rowCount":{"type":"integer","description":"Total rows matching the request, across all pages."},"metadata":{"type":"object","additionalProperties":true,"description":"Google report metadata (currency, time zone, sampling and thresholding flags)."},"propertyQuota":{"type":"object","additionalProperties":true,"description":"Google quota left on this property after the request (tokens per day and per hour, concurrent requests). Cached responses carry the quota from when they were fetched."}}},"GoogleAnalyticsReportFields":{"type":"object","required":["accountId","metrics"],"properties":{"accountId":{"type":"string","description":"Zernio account ID of the Google Analytics connection (platform `googleanalytics`)."},"dimensions":{"type":"array","maxItems":9,"items":{"type":"string"},"description":"GA4 dimension API names, e.g. `date`, `sessionSource`, `pagePath`. List them with GET /v1/analytics/googleanalytics/metadata.","example":["date","sessionDefaultChannelGroup"]},"metrics":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string"},"description":"GA4 metric API names, e.g. `sessions`, `activeUsers`, `keyEvents`, `totalRevenue`.","example":["sessions","activeUsers"]},"dimensionFilter":{"type":"object","additionalProperties":true,"description":"A Google FilterExpression on dimensions, in Google's own shape."},"metricFilter":{"type":"object","additionalProperties":true,"description":"A Google FilterExpression on metrics, in Google's own shape."},"orderBys":{"type":"array","maxItems":10,"items":{"type":"object","additionalProperties":true},"description":"Google OrderBy objects, e.g. `{ \"metric\": { \"metricName\": \"sessions\" }, \"desc\": true }`."},"limit":{"type":"integer","minimum":1,"maximum":10000,"description":"Rows to return. Defaults to Google's default (10000)."}}},"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","shopify","wordpress","wix","linkedinads","metaads","pinterestads","tiktokads","xads","googleads","openaiads","redditads","sms","phone","rcs","whopads","google","microsoft","hubspot","webflow","googleanalytics","imessage","tiktokshop","microsoftads"]},"profileId":{"oneOf":[{"type":"string"},{"$ref":"#/components/schemas/Profile"}]},"username":{"type":"string"},"displayName":{"type":"string"},"platformUserId":{"type":"string","description":"The account's id on its platform, as the platform reports it to Zernio. Stable across reconnects, so use it to match an account against your own records.\n\n- **Instagram Login accounts:** the app-scoped user id (the professional account id is in `metadata.instagramScopedId`).\n- **Instagram via Facebook Login:** the professional account id (`17841...`).\n- **TikTok:** the open_id of Zernio's TikTok app, which differs from the open_id any other app sees for the same user.\n\nEither value can be passed back as `expectedPlatformUserId` on GET /v1/connect/{platform}.\n"},"scopeAreas":{"type":["array","null"],"items":{"type":"string"},"description":"Accounts connected through your own OAuth app: the permission areas the connect requested. Null on accounts connected through Zernio's app."},"oauthAppId":{"type":["string","null"],"description":"The id of your own OAuth app this account connected through (see /v1/connect/oauth-apps); null when it uses Zernio's app."},"tiktokAccountType":{"type":"string","enum":["business","personal","unknown"],"description":"TikTok accounts only. The account type TikTok reported when the account was connected.\n\n- `personal`: cannot use TikTok direct messages through the API (TikTok limits Business Messaging to Business Accounts). Skip the inbox for them and tell the user to switch to a Business Account in the TikTok app, then reconnect.\n- `business`: the prerequisite, not a guarantee. Messaging also needs the messaging scopes granted and TikTok's regional availability.\n- `unknown`: accounts connected before this was captured, or whose grant left out the account-type scope.\n"},"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.\nWhile true, GET /v1/connect/{platform}/ads returns a\nfresh authUrl (implicit force=true) instead of alreadyConnected,\nso re-running the connect flow recovers the account. Cleared\nautomatically when the account is re-authorized.\n"},"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\nor derive from a posting account's OAuth token. null for standalone ads (Google Ads)\nand all posting accounts. Meta ads business-login accounts also have no parent.\n"},"enabled":{"type":"boolean","description":"Whether the user explicitly activated this account. false means the account was created as a side effect (e.g., a posting account auto-created when the user connected ads first).\n\n- GET /v1/accounts still returns such accounts unless `excludeHidden=true` is passed.\n- They cannot be posted to (`ACCOUNT_NOT_ENABLED_FOR_POSTING`) and are not billed as connected accounts.\n- On an ads account (`metaads`, `googleads`, ...) the value does not hide the connection: ads accounts are listed whatever their `enabled` value and keep working for ads.\n"},"metaAdsSyncEnabled":{"type":"boolean","description":"Facebook accounts only (absent on every other platform). Whether this Facebook account syncs the Meta ads of the ad accounts it reaches, the way a `metaads` connection does.\n\nOff by default; set it with `PUT /v1/accounts/{accountId}`. Synced active ads count on the managed ads meter like ads from a Meta Ads connection.\n"},"rateLimitedUntil":{"type":["string","null"],"format":"date-time","description":"End of the account's publishing cooldown. Compare it with the current time: a value in the past means the cooldown has ended (the field is cleared on the next successful publish); null means no cooldown since the last successful publish.\n\n**When it starts.** A post to the account fails with `errorCategory` `user_abuse` (spam, abuse or rate-limit errors), or 10 or more posts to it fail within an hour with `user_content`, `platform_error`, `platform_rate_limit` or `unknown`.\n\n**How long.** It doubles with each start inside a 24-hour window that opens at the first one (10, 20, 40, 80 minutes and so on, capped at 24 hours).\n\nOn a YouTube account with a recorded successful upload, it instead runs until 24 hours after that upload, or 1 hour when that upload is older than 24 hours.\n\n**Effect.** While it is in the future, POST /v1/posts (drafts excepted) and POST /v1/posts/{postId}/retry return 429 for this account. When it starts, this account's pending targets on posts scheduled before the cooldown ends are failed.\n"},"metadata":{"type":"object","description":"Platform-specific metadata. Fields vary by platform.\n\n**WhatsApp accounts:**\n\n- qualityRating: phone number quality rating from Meta (GREEN, YELLOW, RED, or UNKNOWN).\n- nameStatus: display name review status (APPROVED, PENDING_REVIEW, DECLINED, or NONE). A declined or pending name does not by itself block sending; sendability is reported separately via health_status (can_send_message).\n- 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.\n- verifiedName: Meta-verified business display name.\n- displayPhoneNumber: formatted phone number (e.g., \"+1 555-123-4567\").\n- wabaId: WhatsApp Business Account ID.\n- phoneNumberId: Meta phone number ID.\n\n**Meta ads business-login accounts:**\n\n- tokenType: system-user.\n- businessId: the owning Business Manager ID when there is one owner; null for multiple owners.\n- businessIds: owning Business Manager IDs discovered from granted ad accounts.\n- grantedAdAccountIds: ad-account IDs granted to the token.\n- adAccountBusinesses: map from ad-account ID to its owning business ID or null.\n- availablePages: granted Page IDs and names. No Page tokens are exposed.\n- selectedPageId: the Page selected for creatives and lead forms, or null.\n- scopedAdAccountIds: existing sync scope preserved on reconnect.\n\nNon-expiring tokens have no tokenExpiresAt field. Parent posting reconnects do not replace this token.\n\n**LinkedIn accounts:** profileData carries profile details refreshed on each daily snapshot.\n\n- profileData.bio: the member's headline (personal accounts) or the organization description (organization accounts). null when not set.\n- profileData.extraData.vanityName: the member's profile slug, the /in/{vanityName} segment of profileUrl. Personal accounts only; an organization's slug is in metadata.organizationInfo.vanityName.\n\n**Instagram accounts:**\n\n- loginMethod: \"facebook_login\" when connected through Facebook Login; absent for Instagram Login. On facebook_login accounts, comment reads leave hidden comments out entirely instead of returning them with isHidden true.\n- instagramScopedId: the Instagram professional account id (`17841...`). On Instagram Login accounts it is the same whichever app connected the account, while platformUserId is app-scoped. Facebook Login accounts hold this id as platformUserId.\n\n**X (Twitter) accounts:**\n\n- profileData.extraData.isPremium: whether X reports a paid subscription (Basic, Premium, Premium+, or a blue verified badge), which raises the post length limit from 280 to 25,000 characters. Read live at connect and reconnect, refreshed by the daily follower snapshot.\n- Because X intermittently reports no subscription for subscribed accounts, a cancellation is stored on the fourth consecutive daily snapshot reporting it (about four days). Accounts connected before the extraData layout carry the flag at profileData.isPremium.\n"}}},"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.\nFields vary by platform. Only present if metadata has been captured.\n","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)"},"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)"},"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","commerce","creator_campaigns","money","calendar","files"]},"description":"Resource groups this key can NOT access (opt-out denylist). Absent or empty means legacy full access. Each operation's group is published as x-resource-group.\n\nA key with any group disabled is a restricted key (zrk_ prefix) and can never manage API keys, invites, or member identity.\n\nWith 'messages' disabled, the key cannot read or send direct messages through any API surface. It also cannot create or edit a webhook subscription broader than itself: no subscribing to, test-firing, redelivering, or reading delivery logs for message events.\n\nSubscriptions created earlier, from the dashboard, or with a full-access key keep delivering whatever their own `disabledResourceGroups` allows. To restrict an existing integration end to end, restrict the subscription too.\n\nOAuth 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.\n"},"createdBy":{"type":["object","null"],"description":"The team member who created this key. For the team owner's listing this can be any team member; for a non-owner it is always themselves, since a non-owner only ever sees their own keys.","properties":{"id":{"type":"string"},"email":{"type":"string"}}}}},"ConnectedApp":{"type":"object","description":"An OAuth client (AI assistant / MCP connector) authorized by the user and still\nholding at least one live token.\n","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 /\naccess status. Returned by `GET /v1/billing`.\n","properties":{"billingSystem":{"type":"string","enum":["metronome","stripe","shopify"]},"plan":{"type":"object","properties":{"name":{"type":"string"},"isUsageBased":{"type":"boolean"},"isPaid":{"type":"boolean","description":"True when the key belongs to an account with an active paid billing relationship (Stripe subscription, usage-based billing, or Shopify-managed billing)."}}},"shopifyShopDomain":{"type":["string","null"],"description":"myshopify.com domain owning the subscription; present only when billingSystem is shopify."},"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 the usage-based invoice\nbreakdown (the CHARGE view). Returned by `GET /v1/usage`.\n","properties":{"supported":{"type":"boolean","description":"False for legacy Stripe accounts (no usage-based 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"},"imessage":{"type":"number","description":"iMessage sender fees."},"calls":{"type":"number"},"sms":{"type":"number"},"messages":{"type":"number","description":"Managed outbound message fees."},"verify":{"type":"number","description":"Verify (per verification) fees."},"dlc":{"type":"number","description":"10DLC registration (brand + campaign) fees."},"xApi":{"type":"number"},"ads":{"type":"number","description":"Managed ads fees."},"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"},"imessage":{"type":"number"},"calls":{"type":"number"},"sms":{"type":"number"},"messages":{"type":"number"},"verify":{"type":"number"},"dlc":{"type":"number"},"xApi":{"type":"number"},"ads":{"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","imessage","calls","sms","messages","verify","dlc","xApi","ads","credits","other"]},"totalUsd":{"type":"number"},"quantity":{"type":"number"}}}},"peaks":{"type":["object","null"],"description":"Peak counts over the window (usage-based COUNT metrics + live active-number count). Null when `profileId` / `accountId` is set.","properties":{"accounts":{"type":"integer"},"numbers":{"type":"integer"}}},"callUsage":{"type":["object","null"],"description":"Billable call volumes over the window. Null when `profileId` / `accountId` is set.","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.\n\nNull when the account has no billing address on file, the total is zero or negative, or the estimate failed.\n","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)."}}},"attribution":{"type":"object","description":"Present with `groupBy`. The window's spend split per profile or account; `sum(groups) + unattributed` equals `totals` per product.","properties":{"groupBy":{"type":"string","enum":["profile","account"]},"groups":{"type":"array","items":{"$ref":"#/components/schemas/UsageAttributionGroup"}},"unattributed":{"$ref":"#/components/schemas/UsageAttributionSlice","description":"Spend no profile/account can claim: credits, 10DLC fees, Verify, and usage whose record no longer resolves to an account. Zero for a restricted principal."},"totals":{"$ref":"#/components/schemas/UsageAttributionSlice","description":"The window totals; for a restricted principal, the sum of the visible groups."},"restricted":{"type":"boolean","description":"True when the caller (profile-scoped API key or member) cannot see every profile: `groups` are filtered, `totals` sum them, `unattributed` is zero, and the top-level `days` / `totals` / `lineItems` are projected onto the visible groups with `peaks`, `callUsage` and `tax` null."}}},"scope":{"description":"Present with `profileId` / `accountId`: echoes the group the payload was projected onto.","oneOf":[{"type":"object","required":["profileId"],"properties":{"profileId":{"type":"string"}}},{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string"}}}]}}},"UsageAttributionGroup":{"allOf":[{"$ref":"#/components/schemas/UsageAttributionSlice"},{"type":"object","required":["key"],"properties":{"key":{"type":"string","description":"Profile id or account id, per `groupBy`."}}}]},"UsageAttributionSlice":{"type":"object","properties":{"byProduct":{"type":"object","description":"USD per product family.","properties":{"accounts":{"type":"number"},"numbers":{"type":"number"},"imessage":{"type":"number"},"calls":{"type":"number"},"sms":{"type":"number"},"messages":{"type":"number"},"verify":{"type":"number"},"dlc":{"type":"number"},"xApi":{"type":"number"},"ads":{"type":"number"},"credits":{"type":"number"},"other":{"type":"number"}}},"totalUsd":{"type":"number"}}},"UsageStats":{"type":"object","description":"Plan and usage stats. The response shape depends on `billingSystem`:\n\n- Stripe users (default): per-period counters like `usage.uploads` and `usage.profiles`, scoped by the plan's `limits`.\n- Usage-based billing users: `limits` are unlimited (-1). The `usage` block carries connected-account and per-X-operation counts; the `spend` block carries current-period costs plus the X cap.\n","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 accounts on usage-based billing."},"limits":{"type":"object","description":"Plan limits. For accounts on usage-based billing 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`:\nStripe returns `uploads` / `profiles` / `lastReset`;\nusage-based billing returns `connectedAccounts` / `xApiCalls` / `xApiCallsByOperation`.\n","properties":{"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."},"connectedAccounts":{"type":"integer","description":"Usage-based billing only. Accounts currently connected across the team."},"xApiCalls":{"type":"object","deprecated":true,"description":"**Deprecated.** Legacy 3-tier aggregate. Operations outside the\nthree historical prices ($0.005/$0.010/$0.015), notably the\n$0.200 \"Posts with URL\" tier added April 2026, are silently\nexcluded from this shape. Use `xApiCallsByOperation` instead;\nit captures every tier and is the source of truth for\nper-operation call counts.\n","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":"Usage-based billing only. Per-operation X API call counts keyed by\noperation (e.g. `posts_read`, `content_create`,\n`content_create_with_url`). Resolve each key to price and metadata\nvia `GET /v1/billing/x-pricing`. This is the canonical source: it\ncovers every price tier including the $0.200 URL tier that\n`xApiCalls` excludes.\n","example":{"posts_read":42,"content_create":7,"content_create_with_url":3,"dm_interaction_create":1}}}},"spend":{"type":"object","description":"Usage-based billing 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 API spend in cents, summed from\n`xApiCallsByOperation` × per-operation prices. Tier-agnostic\n(covers every price including the $0.200 URL tier). Rounded\nup for conservative enforcement against `xSpendLimitCents`.\n"},"xSpendLimitCents":{"type":["integer","null"],"description":"Monthly X spend cap set by the account owner, or null if no cap.\nWhen current X spend hits this cap, all billable X API activity is\npaused until the billing period resets or the cap is raised, including\npublishing, analytics and inbox sync, and likes, reposts and follows.\n"}}}}},"XApiPricing":{"type":"object","description":"Canonical X API pricing table. Zernio passes X API costs through\nat exact rates with zero markup, so every call you make has a known per-unit\nprice. Use this payload alongside `/v1/usage-stats` (which returns\nper-operation call counts via `xApiCallsByOperation`) to compute exact\ncost attribution by X action.\n","properties":{"currency":{"type":"string","example":"USD"},"markup":{"type":"string","example":"0%","description":"Always 0%, because 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,\n`x_api_200` for $0.200). The first three keys map to the\nlegacy `xApiCalls` aggregate; new tiers (e.g. `x_api_200`\nfor the URL tier added April 2026) are surfaced here but\nnot in the legacy shape.\n","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":"Metering `event_type` emitted when this operation runs."},"displayName":{"type":"string","example":"X API: Posts Read","description":"Human-readable label shown on 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\n$0.005, `x_api_200` for $0.200). Useful for grouping operations\nby price in dashboards.\n","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:\n  * `always`: every call is metered\n  * `analytics_optin`: only when the X account has analytics enabled\n  * `inbox_optin`: only when the X account has inbox sync enabled\n  * `absorbed`: Zernio eats the cost, never billed\n"}}}}}},"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, X)"},"clicks":{"type":"integer","example":0,"description":"Link clicks where the platform reports them. Always 0 on Facebook Page stories: Meta exposes no link-click metric for stories."},"views":{"type":"integer","example":0},"follows":{"type":["integer","null"],"example":0,"description":"Accounts that started following from this post.\n\n- Reported for Instagram feed posts and stories (organic follows), Facebook Reels (Meta post_video_followers) and the TikTok business lane.\n- Null on Instagram Reels and non-Reels video, and on Facebook posts that are not Reels, where Meta does not expose this metric for the media.\n- 0 for other platforms."},"igReelsAvgWatchTime":{"type":"integer","example":0,"description":"Average watch time per play, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). On Facebook it includes replays within a play, so it can exceed the Reel length. 0 for other media and platforms, including regular Facebook videos."},"igReelsVideoViewTotalTime":{"type":"integer","example":0,"description":"Total watch time including replays, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). 0 for other media and platforms, including regular Facebook videos."},"reelsSkipRate":{"type":"number","example":48.8,"description":"Instagram Reels only: percentage (0-100) of initial views that skipped the reel within its first 3 seconds, as reported by Meta.\n\n- Meta labels the metric estimated and in development, so it can move between syncs.\n- 0 for non-Reels media and other platforms.\n- For a post published to several accounts, the aggregate is weighted by views."},"completionRate":{"type":"number","example":0,"description":"Share of viewers who watched the video to the end, 0 to 1, as TikTok reports it. Only for TikTok accounts connected through the TikTok for Business app.\n\n- Delayed T+24-48h, and only for posts active in the last 7 days.\n- 0 for other platforms.\n- For a post published to several accounts, the aggregate is weighted by views."},"profileViews":{"type":"integer","example":0,"description":"Instagram feed posts (images and carousels; 0 on Reels and Stories) and TikTok accounts connected through the TikTok for Business app: profile views from users who reached the profile through this post (TikTok T+24-48h). 0 for other platforms."},"websiteClicks":{"type":"integer","example":0,"description":"TikTok accounts connected through the TikTok for Business app only: clicks on the profile website link attributed to this post (T+24-48h). Also counted inside `clicks`, which sums every profile-link type (website, phone, email, address, app download). 0 for other platforms."},"impressionSources":{"type":"object","additionalProperties":{"type":"number"},"example":{"forYou":0.84,"follow":0.05,"search":0.06,"personalProfile":0.03,"sound":0.01,"directMessage":0,"other":0.01},"description":"Share of views by surface, as fractions 0 to 1. Only for TikTok accounts connected through the TikTok for Business app (T+24-48h, only for posts active in the last 7 days).\n\n- Keys: `forYou`, `follow`, `search`, `personalProfile`, `sound`, `directMessage`, `other`. A surface TikTok adds later appears under a camelCase key derived from its name.\n- Empty object when TikTok reports nothing, and for other platforms.\n- When a post is published to several accounts, each share is weighted by views.\n"},"audienceTypes":{"type":"object","additionalProperties":{"type":"number"},"example":{"follower":0.1,"nonFollower":0.9,"newViewer":0.99,"returnViewer":0.01},"description":"TikTok accounts connected through the TikTok for Business app only: two viewer splits as fractions 0 to 1 (T+24-48h).\n\n- Each pair sums to 1 when present: `follower` + `nonFollower`, and `newViewer` + `returnViewer`. TikTok can report one pair without the other.\n- Empty object when TikTok reports nothing, and for other platforms.\n- Views-weighted across accounts, like impressionSources.\n"},"audienceCountries":{"type":"object","additionalProperties":{"type":"number"},"example":{"US":0.62,"GB":0.11,"CA":0.07,"DE":0.05,"other":0.15},"description":"TikTok accounts connected through the TikTok for Business app only: share of views by viewer country, as fractions 0 to 1, keyed by upper-case ISO-3166 alpha-2 code. Available T+24-48h, only for posts active in the last 7 days.\n\nAt most 20 country keys plus `other`. The catch-all bucket TikTok sends, any country below 0.001 and anything past the twentieth all sum into `other`, so the values still add up to 1.\n\nEmpty object when TikTok reports nothing, and for other platforms. Views-weighted across accounts like impressionSources.\n"},"replays":{"type":"integer","example":1208,"description":"Facebook Reels only: plays that were replays (Meta fb_reels_replay_count). Summed across accounts. 0 for other media and platforms."},"retentionCurve":{"type":"object","additionalProperties":{"type":"number"},"example":{"0":0.9923,"1":0.9937,"4":0.8637,"8":0.5313,"12":0.3605},"description":"Facebook Reels and TikTok business lane: share of viewers still watching at each second of playback, as fractions 0 to 1. Keys are whole seconds from the start of a play (\"3\" is the share still watching at 3 s). Empty object for other media and platforms.\n\n- Facebook Reels (Meta post_video_retention_graph): the base is a subset of plays that Meta selects and does not expose. On small Reels it can be far below views (6 of 51 measured), so a value is a share of that subset, not of all plays.\n- Facebook Reels length: loops count as continued playback, so a short Reel's curve runs past its length (an 8 s Reel has keys \"0\" to \"12\"). Meta returns at most 41 points, so a long Reel covers only its first 40 s.\n- TikTok accounts connected through the TikTok for Business app (TikTok video_view_retention): one point per whole second, at most 61 points, thinned evenly on videos longer than 60 s.\n\nOn a cross-posted post this is the curve of the account with the most views among those reporting one, never a blend: curves from different platforms and accounts measure different audiences and different seconds. Each platformAnalytics entry keeps its own curve.\n"},"reposts":{"type":"integer","example":0,"description":"Reposts of the media by other users, minus deleted reposts, on feed posts, reels and stories. Instagram accounts connected with Facebook Login only.\n\n- Instagram Login accounts: always 0 (Meta does not expose this metric for them).\n- Other platforms: 0, including Threads, where reposts are counted in shares instead."},"videoDurationSeconds":{"type":["integer","null"],"example":30,"description":"Video length in seconds. Null when unknown: platforms that do not report a length, non-video media, or when Instagram does not expose the media URL (e.g. reels with copyrighted audio).\n\n- YouTube: filled for public videos once their analytics next refresh (from the Data API; live streams may report null). The Data API has no Shorts flag: a video over 180 seconds cannot be a Short, but a shorter one may be a regular upload.\n- Instagram Reels: also filled. Combine with igReelsAvgWatchTime (ms) to estimate retention."},"engagementRate":{"type":"number","example":6.59,"description":"Percentage, rounded to 2 decimals: (likes + comments + shares + saves) / (impressions or reach or views) * 100. Clicks and follows are never counted.\n\nThe denominator is the FIRST of impressions, reach, views that is non-zero, so the basis varies by post: impressions if present, else reach, else views. For a single consistent basis (e.g. interactions / reach), compute it from the raw fields above.\n\nOn the post-level roll-up of a cross-posted post, the denominator is the SUM of the denominators resolved per platform entry. An entry reporting none of impressions, reach or views is excluded from both sides of the ratio. Each platformAnalytics entry below keeps its own single denominator.\n\nThe engagementRate on the LinkedIn account endpoints uses a different formula."},"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":"Failure detail:\n\n- Failed entries: why the post failed to publish.\n- Unavailable entries: why analytics cannot be synced (e.g. Google Business Profile, a TikTok upload that never received a video id).\n- Pending entries: the most recent analytics sync error for the account (null while no sync has failed), cleared after the next successful sync."},"errorCode":{"type":["string","null"],"enum":["post_not_found","not_post_owner","permission_missing",null],"description":"Stable machine-readable reason for errorMessage. New values may be added.\n\n- post_not_found: the post was deleted or is no longer visible to the account.\n- not_post_owner: the post is owned by another Page or user (collab or visitor post); its analytics cannot be read with this Page's token.\n- permission_missing: the last analytics sync of the Facebook account failed because the Page no longer grants pages_read_engagement (pending entries only).\n- null: no stable code; read errorMessage."},"isOwner":{"type":["boolean","null"],"description":"Facebook only: true when the connected Page authored the post, false when Facebook reports another author (a collab post), null when unknown or for other platforms."}}},"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","scheduled","publishing","draft","cancelled"],"description":"Overall post status. \"partial\" when some platforms published and others failed.\n\nWhile any platform is still pending or processing, the post's own status is returned instead (usually scheduled or publishing), even if another platform already published.\n\nA post with no published or failed platform (for example every platform cancelled) returns its own status with syncStatus unavailable and no platformAnalytics."},"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","description":"Cover image URL. Facebook, Instagram and TikTok covers whose platform CDN link expired are re-read from the platform and served from Zernio storage, so that URL does not expire and can be cached."},"mediaType":{"type":["string","null"],"enum":["image","video","carousel","text"]},"mediaItems":{"type":"array","description":"All media items for this post. Carousel posts have one entry per slide.\n\n- Facebook and Instagram images and video covers whose Meta CDN links expired are re-read and served from Zernio storage (non-expiring).\n- Facebook and Instagram video file URLs, and LinkedIn media URLs, stay the platform's signed links and are refreshed on read once they lapse.\n","items":{"type":"object","properties":{"type":{"type":"string","enum":["image","video"]},"url":{"type":["string","null"],"format":"uri","description":"'Direct URL to the media file. Null when the platform withholds it: check mediaStatus before downloading. Instagram omits the video file for Reels it flags as containing copyrighted material (its docs name audio as the usual cause), so type stays \"video\" while the file is permanently unreachable.'"},"thumbnail":{"type":["string","null"],"format":"uri","description":"Thumbnail URL (same as url for images). Still present when url is null."},"altText":{"type":"string","description":"Accessibility alt text set on the media, when present."},"mediaStatus":{"type":"string","enum":["available","unavailable"],"description":"unavailable means the media file could not be retrieved (url is null or, for LinkedIn videos, a cover image standing in for the file). available or absent means the file is available at url (older synced items omit the field)."},"unavailableReason":{"type":"string","enum":["platform_withheld"],"description":"Why the file is missing. platform_withheld means the platform declined to return it and retrying will not help."}}}},"mediaProductType":{"type":"string","description":"Instagram only: the platform media product type (e.g. FEED, REELS, STORY, AD). Absent when the platform did not report it."},"isAiGenerated":{"type":"boolean","description":"Instagram only: whether Instagram labeled the media as AI-generated. Absent when the platform did not report it."},"isSharedToFeed":{"type":"boolean","description":"Instagram reels only: whether the reel is also shared to the main feed. Absent when the platform did not report it."},"mediaAudioType":{"type":"string","description":"Instagram only: audio type of the media (MUSIC or ORIGINAL_SOUND). Absent when the platform did not report it."}}},"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"},"isAd":{"type":"boolean","description":"True when this post's metrics include paid delivery, so organic reporting should exclude it.\n\nSet for LinkedIn dark posts and for TikTok posts one of your TikTok ads promotes (Spark / boosted).\n\nTikTok exposes no ad flag of its own. A video created by an uploaded-asset (non-Spark) TikTok ad is posted to the profile with a fresh organic id and cannot be detected, so those still report false.\n"},"profileId":{"type":["string","null"]},"thumbnailUrl":{"type":"string","format":"uri","description":"Cover image URL. Facebook, Instagram and TikTok covers whose platform CDN link expired are re-read from the platform and served from Zernio storage, so that URL does not expire and can be cached."},"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.\n\n- Facebook and Instagram images and video covers whose Meta CDN links expired are re-read and served from Zernio storage (non-expiring).\n- Facebook and Instagram video file URLs, and LinkedIn media URLs, stay the platform's signed links and are refreshed on read once they lapse.\n","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."}}}},"mediaProductType":{"type":"string","description":"Instagram only: the platform media product type (e.g. FEED, REELS, STORY, AD). Absent when the platform did not report it."},"isAiGenerated":{"type":"boolean","description":"Instagram only: whether Instagram labeled the media as AI-generated. Absent when the platform did not report it."},"isSharedToFeed":{"type":"boolean","description":"Instagram reels only: whether the reel is also shared to the main feed. Absent when the platform did not report it."},"mediaAudioType":{"type":"string","description":"Instagram only: audio type of the media (MUSIC or ORIGINAL_SOUND). Absent when the platform did not report it."}}}},"pagination":{"$ref":"#/components/schemas/Pagination"},"accounts":{"type":"array","description":"Connected 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"}}},"AnalyticsDeltaEntry":{"type":"object","description":"One changed analytics snapshot. Metrics are the absolute values recorded at\n`syncedAt`, not the amount they moved by since the previous snapshot, so a later\nentry for the same `postId` always supersedes an earlier one.\n","required":["postId","accountId","profileId","platform","platformPostId","publishedAt","syncedAt","isDeleted","metrics"],"properties":{"postId":{"type":"string","description":"External post ID. The same identifier as `posts[]._id` in GET /v1/analytics."},"accountId":{"type":"string","description":"Account this post was published through"},"profileId":{"type":"string","description":"Profile the account belongs to"},"platform":{"type":"string","example":"youtube"},"platformPostId":{"type":"string","description":"Platform-side post ID (for example the YouTube video ID)"},"publishedAt":{"type":"string","format":"date-time","description":"When the post was published, ISO-8601 UTC"},"syncedAt":{"type":"string","format":"date-time","description":"When the sync cycle that produced this snapshot STARTED, ISO-8601 UTC.\n\nThis is NOT the order entries arrive in and not a resume point: a slow cycle writes its rows after a faster cycle that started later, so `syncedAt` can go backwards between consecutive entries. Use `nextCursor` to resume.\n"},"isDeleted":{"type":"boolean","description":"True when the post was detected as deleted on the platform at this sync"},"metrics":{"type":"object","description":"Metrics a platform does not report are 0, not absent.","required":["impressions","reach","likes","comments","shares","saves","sends","clicks","views","follows","igReelsAvgWatchTime","igReelsVideoViewTotalTime","reposts","reelsSkipRate","completionRate","profileViews","websiteClicks","impressionSources","audienceTypes","audienceCountries"],"properties":{"impressions":{"type":"integer"},"reach":{"type":"integer"},"likes":{"type":"integer"},"comments":{"type":"integer"},"shares":{"type":"integer"},"saves":{"type":"integer"},"sends":{"type":"integer"},"clicks":{"type":"integer"},"views":{"type":"integer"},"follows":{"type":"integer","description":"Follows attributed to this post (Instagram feed and stories, Facebook Reels, TikTok business lane)"},"igReelsAvgWatchTime":{"type":"integer","description":"Average watch time per play, in milliseconds (Instagram Reels, Facebook Reels, TikTok business videos)"},"igReelsVideoViewTotalTime":{"type":"integer","description":"Total watch time including replays, in milliseconds (Instagram Reels, Facebook Reels, TikTok business videos)"},"reposts":{"type":"integer"},"reelsSkipRate":{"type":"number","description":"Instagram Reels skip rate, 0 to 1"},"completionRate":{"type":"number","description":"TikTok business lane: share of viewers who watched to the end, 0 to 1"},"profileViews":{"type":"integer","description":"Instagram feed posts (images and carousels; 0 on Reels and Stories) and TikTok business lane: profile views attributed to the post"},"websiteClicks":{"type":"integer","description":"TikTok business lane: website-link clicks attributed to the post (also inside clicks)"},"impressionSources":{"type":"object","additionalProperties":{"type":"number"},"description":"TikTok business lane: share of views by surface (forYou, follow, search, personalProfile, sound, directMessage, other), fractions 0 to 1. Empty object elsewhere."},"audienceTypes":{"type":"object","additionalProperties":{"type":"number"},"description":"TikTok business lane: follower / nonFollower and newViewer / returnViewer shares, fractions 0 to 1. Empty object elsewhere."},"audienceCountries":{"type":"object","additionalProperties":{"type":"number"},"description":"TikTok business lane: viewer-country shares keyed by ISO-3166 alpha-2, fractions 0 to 1, top 20 with the tail in `other`. Empty object elsewhere."},"replays":{"type":"integer","description":"Facebook Reels only: plays that were replays. 0 elsewhere."},"retentionCurve":{"type":"object","additionalProperties":{"type":"number"},"description":"Share of viewers still watching at each second of playback, as fractions 0 to 1. Filled for Facebook Reels and the TikTok business lane; an empty object for other media and platforms.\n\n**Facebook Reels** (Meta post_video_retention_graph):\n\n- The base is a subset of plays that Meta selects and does not expose. On small Reels it can be far below views (6 of 51 measured), so a value is a share of that subset, not of all plays.\n- Keys are whole seconds from the start of a play (\"3\" is the share still watching at 3 s).\n- Loops count as continued playback, so a short Reel's curve runs past its length (an 8 s Reel has keys \"0\" to \"12\").\n- Meta returns at most 41 points, so a long Reel covers only its first 40 s.\n\n**TikTok** (accounts connected through the TikTok for Business app, from TikTok video_view_retention): share still watching at each whole second, fractions 0 to 1, at most 61 points, thinned evenly on videos longer than 60 s."}}}}},"AnalyticsDeltaResponse":{"type":"object","required":["data","nextCursor","hasMore"],"properties":{"data":{"type":"array","description":"Changed snapshots, oldest first, in the order the feed received them. Empty on\nthe bootstrap call (no `cursor` supplied) and whenever nothing has changed\nsince your cursor.\n","items":{"$ref":"#/components/schemas/AnalyticsDeltaEntry"}},"nextCursor":{"type":"string","description":"Cursor to send on the next call. ALWAYS present, including on an empty page,\nso you always have something to advance with, and it never moves backwards.\nOpaque: pass it back verbatim, and do not parse, construct or compare cursors.\n","example":"v1.WyIyMDI2LTA5LTAxIDE3OjEyOjA0IiwiNjVmMWMwYTllMmI1YWYwMDEyYWIzNGNkIl0"},"hasMore":{"type":"boolean","description":"True when more changes are already waiting past `nextCursor`, so call again\nimmediately. False means you are caught up: keep `nextCursor` and poll again\nlater. This feed never ends, so `hasMore: false` does NOT mean `nextCursor`\nis null.\n"}}},"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 a percentage rounded to 2 decimals: (reactions + comments + shares + saves + sends) / impressions * 100.\n\nClicks are not counted and there is no fallback denominator, so this is 0 whenever impressions is 0. NOT the same formula as PostAnalytics.engagementRate on GET /v1/analytics."}}},"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"}}},"PostsListResponse":{"type":"object","properties":{"posts":{"type":"array","items":{"$ref":"#/components/schemas/Post"}},"pagination":{"allOf":[{"$ref":"#/components/schemas/Pagination"},{"type":"object","properties":{"nextCursor":{"type":["string","null"],"description":"Cursor for the next page in the same sortBy order. Send it back as `cursor`. Null on the last page, and always null for `sortBy=status` or `sortBy=platform`. Absent for `source=external`."}}}]}}},"PostGetResponse":{"type":"object","properties":{"post":{"$ref":"#/components/schemas/Post"}}},"TikTokSmartPlusReviewStatus":{"type":"string","enum":["approved","partially_approved","rejected","unknown"],"description":"TikTok `review_status` normalized: ALL_AVAILABLE -> approved, PART_AVAILABLE -> partially_approved (delivers in part of the targeted locations), UNAVAILABLE -> rejected, anything else or missing -> unknown (see `rawReviewStatus`)."},"TikTokSmartPlusAdLevelReview":{"type":["object","null"],"description":"The ad-level verdict of a Smart+ ad (`smart_plus_ad_review_infos`). Null when TikTok returned none.","properties":{"reviewStatus":{"$ref":"#/components/schemas/TikTokSmartPlusReviewStatus"},"rawReviewStatus":{"type":["string","null"],"description":"TikTok `review_status`, verbatim."},"rejectReasons":{"type":"array","items":{"type":"string"},"description":"Every distinct reason across `rejections`."},"passedLocations":{"type":"array","items":{"type":"string"},"description":"Location codes that passed the review."},"appealStatus":{"type":["string","null"],"description":"TikTok `appeal_status`, verbatim: NOT_APPEALED, APPEALING, APPEAL_SUCCESSFUL, APPEAL_FAILED, APPEAL_DONE."},"appealRejectReasons":{"type":"array","items":{"type":"string"}},"rejections":{"type":"array","items":{"$ref":"#/components/schemas/TikTokReviewRejection"}}}},"TikTokSmartPlusMaterialReview":{"type":"object","description":"The verdict of one creative of a Smart+ ad (`material_review_infos`).","properties":{"adMaterialId":{"type":"string","description":"TikTok `ad_material_id` of the creative inside this ad."},"materialType":{"type":["string","null"],"enum":["spark_post","video","carousel","catalog_carousel",null],"description":"Null for a creative TikTok added on its own or a carousel image."},"tiktokItemId":{"type":["string","null"],"description":"The TikTok post id when the creative is a Spark post."},"videoId":{"type":["string","null"]},"name":{"type":["string","null"]},"operationStatus":{"type":["string","null"],"description":"TikTok `material_operation_status`: ENABLE or DISABLE."},"reviewStatus":{"$ref":"#/components/schemas/TikTokSmartPlusReviewStatus"},"rawReviewStatus":{"type":["string","null"],"description":"TikTok `review_status`, verbatim."},"rejectReasons":{"type":"array","items":{"type":"string"},"description":"Every distinct reason across `rejections`. Empty when approved."},"passedLocations":{"type":"array","items":{"type":"string"}},"rejections":{"type":"array","items":{"$ref":"#/components/schemas/TikTokReviewRejection"}}}},"TikTokReviewRejection":{"type":"object","description":"One TikTok `reject_info` entry.","properties":{"reasons":{"type":"array","items":{"type":"string"}},"suggestion":{"type":["string","null"],"description":"TikTok's advice for fixing the rejection."},"forbiddenPlacements":{"type":"array","items":{"type":"string"}},"forbiddenAges":{"type":"array","items":{"type":"string"}},"forbiddenLocations":{"type":"array","items":{"type":"string"}},"content":{"type":["object","null"],"description":"The content TikTok rejected.","properties":{"type":{"type":["string","null"],"description":"TikTok `content_type`, verbatim (ModeString, ModeImage, ModeVideo, ModeMusic, LandingPage, ...)."},"text":{"type":["string","null"]},"imageId":{"type":["string","null"]},"videoId":{"type":["string","null"]},"musicId":{"type":["string","null"]}}}}},"TikTokDryRunVerdict":{"type":"object","required":["dryRun","canPublish","tiktok"],"properties":{"dryRun":{"type":"boolean","description":"Always true on this response"},"canPublish":{"type":"boolean","description":"True only when every evaluated TikTok account can publish now"},"tiktok":{"type":"array","description":"One verdict per `tiktok` entry in the request, in request order","items":{"type":"object","required":["accountId","canPublish","reason"],"properties":{"accountId":{"type":"string"},"canPublish":{"type":"boolean"},"alreadyPostedToday":{"type":"boolean","description":"Whether this account already published a Direct Post today (an account that did can keep publishing). Absent for Creator Inbox drafts and when no per-user limit applies."},"reason":{"type":"string","description":"Human-readable explanation of the verdict"}}}}}},"PostCreateResponse":{"type":"object","properties":{"message":{"type":"string"},"post":{"$ref":"#/components/schemas/Post"},"warnings":{"type":"array","description":"Advisory notices about a post that was still created: media truncated for a platform, a recycling caveat, or a field that was ignored because it sat outside platforms[].platformSpecificData. Absent when there are none.","items":{"type":"string"}}}},"PostUpdateResponse":{"type":"object","properties":{"message":{"type":"string"},"post":{"$ref":"#/components/schemas/Post"},"warnings":{"type":"array","items":{"type":"string"}}}},"PostPublishIncompleteResponse":{"type":"object","description":"Body of the 207 returned by createPost and updatePost when the post was saved but the inline publish did not fully succeed. Read `post.status` to tell the three outcomes apart.","properties":{"post":{"$ref":"#/components/schemas/Post"},"message":{"type":"string","description":"Human-readable summary of the publish outcome."},"error":{"type":"string","description":"Present when no platform published. Absent on a partial success. Informational only; the per-platform detail is in `platformResults` and in `post.platforms[]`."},"platformResults":{"type":"array","description":"Per-platform outcome of the publish attempt. Omitted when the attempt aborted before producing per-platform results (for example the post was already being processed); read `post.platforms[]` in that case.","items":{"type":"object","required":["platform","status","error"],"properties":{"platform":{"type":"string","description":"Platform slug, matching `post.platforms[].platform`."},"status":{"type":"string","example":"failed","description":"Per-platform status: pending, processing, published, failed, cancelled, uploading."},"error":{"type":["string","null"],"description":"Failure detail for this platform, or null when it did not fail."}}}},"warnings":{"type":"array","description":"Advisory notices about the post that was still created. Absent when there are none.","items":{"type":"string"}}}},"PostDeleteResponse":{"type":"object","properties":{"message":{"type":"string"}}},"PostRetryResponse":{"type":"object","properties":{"message":{"type":"string"},"post":{"$ref":"#/components/schemas/Post"}}},"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"}}},"InboundActivity":{"type":"object","required":["firstMessageAt","lastMessageAt","firstCommentAt","lastCommentAt"],"description":"When inbound messages and comments were first and last seen for the account. Only events matched to this account count. WhatsApp delivery statuses for outbound messages do not count, so the stamps of a number that only sends stay null. The stamps reset on every connect.","properties":{"firstMessageAt":{"type":["string","null"],"format":"date-time","description":"First inbound message since the latest connect, or since tracking began for an account connected before it. Null when none yet."},"lastMessageAt":{"type":["string","null"],"format":"date-time","description":"Latest inbound message, precise to about one hour. Null when none yet."},"firstCommentAt":{"type":["string","null"],"format":"date-time","description":"First inbound comment since the latest connect, or since tracking began for an account connected before it. Null when none yet."},"lastCommentAt":{"type":["string","null"],"format":"date-time","description":"Latest inbound comment, precise to about one hour. Null when none yet."}}},"ListedAccount":{"allOf":[{"$ref":"#/components/schemas/SocialAccount"},{"type":"object","properties":{"inboundActivity":{"anyOf":[{"$ref":"#/components/schemas/InboundActivity"},{"type":"null"}],"description":"Present only on WhatsApp, Instagram and Facebook accounts. All four stamps are null when no inbound event has been seen since the latest connect. Null for an account connected before tracking shipped until its first inbound event or its next connect."}}}]},"AccountsListResponse":{"type":"object","required":["accounts","hasAnalyticsAccess"],"properties":{"accounts":{"type":"array","items":{"$ref":"#/components/schemas/ListedAccount"}},"hasAnalyticsAccess":{"type":"boolean","description":"Whether user has analytics add-on access"},"pagination":{"description":"Present on a paginated request: `{ page, limit, total, pages }` with page and limit, `{ limit, nextCursor }` with cursor paging (limit alone or cursor).","oneOf":[{"$ref":"#/components/schemas/Pagination"},{"$ref":"#/components/schemas/AccountCursorPagination"}]},"profileTotals":{"type":"object","additionalProperties":{"type":"integer"},"description":"Only with profileIds and perProfile. Accounts matching the filters per profile ID; a profile with none is absent."},"statusCounts":{"type":"object","description":"Only with includeStatusCounts=true. Counts over every filter of the request except status.","required":["all","disconnected"],"properties":{"all":{"type":"integer","description":"Accounts matching the filters in any status."},"disconnected":{"type":"integer","description":"Of those, the accounts that need reconnection."}}}}},"AccountCursorPagination":{"type":"object","required":["limit","nextCursor"],"properties":{"limit":{"type":"integer"},"nextCursor":{"type":["string","null"],"description":"Opaque cursor for the next page; pass it back as `cursor`. Null on the last page."}}},"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"},"pagination":{"description":"Only present when limit or cursor is sent.","$ref":"#/components/schemas/AccountCursorPagination"}}},"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","null"],"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"}}},"User":{"type":"object","properties":{"_id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"},"disabledResourceGroups":{"type":"array","items":{"type":"string"},"description":"Resource groups turned off for this team member. Empty for owners and unrestricted members."},"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"}}},"AdsListResponse":{"type":"object","properties":{"ads":{"type":"array","items":{"$ref":"#/components/schemas/Ad"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"backfillPending":{"type":"boolean","description":"Meta only. Present and true while historical data is being backfilled."}}},"AdsAlert":{"type":"object","properties":{"id":{"type":"string","description":"Stable for the same problem on the same entity. Pass it to POST /v1/ads/alerts/{alertId}/dismiss."},"kind":{"type":"string","enum":["ad_rejected","delivery_issue","payment","budget_limited","spend_no_results","connection_lost","sync_failing"]},"severity":{"type":"string","enum":["error","warning","info"]},"title":{"type":"string"},"message":{"type":"string","description":"What happened, in plain words. For a rejection or delivery issue, the platform's own reason when it gave one."},"platform":{"type":"string"},"platformAdAccountId":{"type":"string"},"entity":{"type":"object","properties":{"level":{"type":"string","enum":["ad_account","campaign","ad_set","ad"]},"id":{"type":"string","description":"The platform id of the entity."},"name":{"type":["string","null"]}}},"adId":{"type":"string","description":"The Zernio ad id when the entity is an ad, for GET /v1/ads/{adId}."},"accountId":{"type":"string","description":"The Zernio ads connection, on connection_lost and sync_failing alerts."},"currency":{"type":["string","null"]},"detectedAt":{"type":"string","format":"date-time"},"fix":{"type":"object","description":"Where to fix it: a page on the platform, or for connection_lost the Zernio dashboard path (starting with /) where the connection is reconnected.","properties":{"label":{"type":"string"},"url":{"type":"string","format":"uri-reference"}}},"dismissed":{"type":"boolean"}}},"AdTreeResponse":{"type":"object","properties":{"campaigns":{"type":"array","items":{"$ref":"#/components/schemas/AdTreeCampaign"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"syncedAt":{"type":["string","null"],"format":"date-time","description":"When the most recently synced ad on this page was last read from the platform. Null before the first sync."},"previousRange":{"type":"object","description":"Only with `compare=previous`. The range `previousMetrics` covers.","properties":{"fromDate":{"type":"string","format":"date"},"toDate":{"type":"string","format":"date"}}},"resultMetrics":{"type":"array","description":"Only with `results=true`. Your metrics and formulas, to label each campaign's `results`.","items":{"$ref":"#/components/schemas/CampaignResultMetric"}},"backfillPending":{"type":"boolean","description":"Meta only. Present and true while historical data is being backfilled."}}},"AdsPerformanceResponse":{"type":"object","required":["ads"],"properties":{"ads":{"type":"array","items":{"type":"object","properties":{"adId":{"type":"string","description":"Zernio ad ID."},"platformAdId":{"type":["string","null"]},"platform":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"campaignName":{"type":["string","null"]},"adSetName":{"type":["string","null"]},"currency":{"type":["string","null"],"description":"ISO 4217 code of the ad's money metrics."},"creative":{"type":"object","properties":{"type":{"type":["string","null"],"enum":["image","video","carousel","document",null]},"thumbnailUrl":{"type":["string","null"]},"headline":{"type":["string","null"]},"body":{"type":["string","null"]},"linkUrl":{"type":["string","null"]}}},"metrics":{"type":"object","properties":{"spend":{"type":"number","description":"In the ad's currency."},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"ctr":{"type":"number","description":"Percent."},"conversions":{"type":"number","description":"Results over the range (see AdMetrics.conversions)."},"costPerConversion":{"type":"number"},"purchaseValue":{"type":"number"},"roas":{"type":"number"},"conversionsByType":{"type":"object","additionalProperties":{"type":"number"},"description":"`conversions` split by what was counted (Meta action_type or Google conversion action name)."}}}}}}}},"AdsTimelineResponse":{"type":"object","properties":{"backfillPending":{"type":"boolean","description":"Meta only. Present and true while historical data is being backfilled."},"previousRows":{"type":"array","description":"Only with `compare=previous`. The daily rows of `previousRange`, in the same shape as `rows`.","items":{"type":"object","additionalProperties":true}},"previousRange":{"type":"object","description":"Only with `compare=previous`. The period of the same length that ends the day before `fromDate`.","properties":{"fromDate":{"type":"string","format":"date"},"toDate":{"type":"string","format":"date"}}},"rows":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"currency":{"type":["string","null"],"description":"ISO 4217 currency of every money field in this row (spend, cpc, cpm, costPerConversion, purchaseValue, actionValues). Null when the currency of the row's ad accounts is unknown. Added 2026-10-23.\n\nAn account whose ad accounts bill in different currencies gets one row per currency for that day, never a sum across currencies."},"spend":{"type":"number","description":"Native currency units (matches /ads/tree convention), in `currency`."},"impressions":{"type":"integer"},"reach":{"type":"integer","description":"Reach summed across the account's ads for this single day. A person seen by two ads the same day counts twice, and reach is de-duplicated per day only: do NOT sum it across days (people reached on multiple days would be double-counted)."},"clicks":{"type":"integer"},"engagement":{"type":"integer"},"ctr":{"type":"number","description":"Click-through rate as a percentage (0 to 100)."},"cpc":{"type":"number","description":"Cost per click in native currency."},"cpm":{"type":"number","description":"Cost per 1000 impressions in native currency."},"conversions":{"type":"number","description":"Sum of conversion events over the range. Fractional values are normal (attribution splitting + Google modeled conversions). Meta: the ad set Ads Manager Results (see AdMetrics.conversions). Google: tracked conversions. X / LinkedIn: reported website/lead conversions (added 2026-07)."},"allConversions":{"type":"number","description":"All conversions, including actions excluded from the Conversions column (Google metrics.all_conversions). 0 on platforms without the concept."},"conversionsByType":{"type":"object","additionalProperties":{"type":"number"},"description":"`conversions` split by what was counted. Keys are the Meta action_type (e.g. `offsite_conversion.fb_pixel_purchase`) or the Google conversion action name, so a goal change shows as one key ending and another starting. Meta and Google only; empty before 2026-11."},"costPerConversion":{"type":"number"},"actions":{"type":"object","additionalProperties":{"type":"number"},"description":"Per-action-type counts merged across all ads on this day. Keys are platform-native action types."},"actionValues":{"type":"object","additionalProperties":{"type":"number"},"description":"Monetary mirror of `actions` in native currency."},"purchaseValue":{"type":"number","description":"Sum of purchase-type action values on this day, native currency."},"roas":{"type":"number","description":"Derived purchaseValue / spend."}}}}}},"AdNegativeKeywordList":{"type":"object","properties":{"id":{"type":"string","pattern":"^\\d+$","description":"Google shared set id."},"resourceName":{"type":"string","description":"Google shared set resource name."},"name":{"type":"string","description":"List name."},"memberCount":{"type":"integer","description":"Number of keywords in the list."},"referenceCount":{"type":"integer","description":"Number of resources referencing the list."}}},"AdNegativeKeywordListKeyword":{"type":"object","properties":{"criterionId":{"type":"string","pattern":"^\\d+$","description":"Google shared criterion id."},"text":{"type":"string","description":"Keyword text."},"matchType":{"type":"string","enum":["broad","phrase","exact"]}}},"CampaignAnalyticsResponse":{"type":"object","properties":{"backfillPending":{"type":"boolean","description":"Meta only. Present and true while historical data is being backfilled."},"campaign":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"platform":{"type":"string"},"status":{"type":["string","null"],"description":"The platform's own campaign status in its vocabulary (Google ENABLED / PAUSED / REMOVED, Meta ACTIVE / PAUSED, ...), the same value as platformCampaignStatus on /v1/ads/campaigns and /v1/ads/tree. For a campaign synced before that value was stored it falls back to an active child ad's status, else the newest ad's."},"budget":{"anyOf":[{"$ref":"#/components/schemas/AdCampaignBudget"},{"type":"null"}],"description":"Google only. Latest synced campaign budget, or null before sync."},"currency":{"type":["string","null"],"description":"ISO 4217 code of the ad account (e.g. USD, THB). All money values in `summary` and `daily` are in this currency."}}},"analytics":{"type":"object","properties":{"summary":{"allOf":[{"$ref":"#/components/schemas/AdMetrics"},{"type":"object","properties":{"searchImpressionShare":{"type":["number","null"],"description":"Google only. Date-range ratio, not a percentage. Null when unavailable; Google's threshold sentinel values are preserved."},"searchBudgetLostImpressionShare":{"type":["number","null"],"description":"Google only. Date-range ratio, not a percentage. Null when unavailable; Google's threshold sentinel values are preserved."},"searchRankLostImpressionShare":{"type":["number","null"],"description":"Google only. Date-range ratio, not a percentage. Null when unavailable; Google's threshold sentinel values are preserved."},"searchTopImpressionShare":{"type":["number","null"],"description":"Google only. Date-range ratio, not a percentage. Null when unavailable; Google's threshold sentinel values are preserved."},"searchAbsoluteTopImpressionShare":{"type":["number","null"],"description":"Google only. Date-range ratio, not a percentage. Null when unavailable; Google's threshold sentinel values are preserved."}}}]},"impressionShareCache":{"type":"object","description":"Google only. Cache status of the single date-range impression-share query.","properties":{"cachedAt":{"type":["string","null"],"format":"date-time"},"stale":{"type":"boolean"}}},"daily":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AdMetrics"},{"type":"object","properties":{"date":{"type":"string","format":"date"}}}]}},"breakdowns":{"type":"object","description":"Requested demographic breakdowns, keyed by dimension. Fetched live from the\nplatform per request and never stored, so these rows can carry fields the\nstored `summary` and `daily` series do not.\n\nLinkedIn rows carry `value` (the pivot URN), `name` (resolved label where\nLinkedIn provides one), the usual spend/impressions/clicks/ctr/cpc/cpm/engagement\nfigures, plus two reach fields:\n\n- `reach`: the segment's `approximateMemberReach`.\n- `audiencePenetration`: LinkedIn's own ratio of members reached to the size of\n  the targeted audience, passed through verbatim.\n\nLinkedIn withholds both below its audience privacy threshold, in which case the\nkeys are ABSENT rather than 0. `audiencePenetration` is available here only: it\nis not part of the stored metrics series.\n\nTikTok rows are keyed by TikTok's own dimension name (`country_code` for\n`country`, `platform` for `publisher_platform`). `placement` rows carry the\nlabel TikTok Ads Manager shows (`TikTok`, `TikTok Ad Network`, `News Feed App Series`)\nin `placement` and TikTok's API value (`PLACEMENT_TIKTOK`, `PLACEMENT_PANGLE`,\n`PLACEMENT_GLOBAL_APP_BUNDLE`) in `placementRaw`; a value without a known label\ncarries the raw value in both.\n\nA requested dimension with no data in the range is an empty array.\n","additionalProperties":{"type":"array","items":{"type":"object"}}},"unsupportedBreakdowns":{"type":"array","items":{"type":"string"},"description":"Requested breakdowns this platform cannot break down by (e.g. region on TikTok, any breakdown on Google). Absent when every requested breakdown is supported."},"breakdownHints":{"type":"object","additionalProperties":{"type":"string"},"description":"Guidance for some names in unsupportedBreakdowns, keyed by that name (e.g. placement on Meta points at publisher_platform and platform_position; platform_position on TikTok points at placement). Absent when no unsupported name has a hint."},"breakdownErrors":{"type":"array","description":"TikTok only: breakdowns the platform failed to return (rate limit, permission, rejected query). Each one is an empty array under breakdowns; summary and daily are unaffected. Absent when every breakdown answered.","items":{"type":"object","properties":{"breakdown":{"type":"string"},"message":{"type":"string","description":"The platform's error message."}}}},"breakdownDroppedMetrics":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"TikTok only: TikTok metric names TikTok refused for a breakdown, keyed by the requested breakdown (e.g. total_purchase and total_purchase_value have no relation to platform, ac or language). Absent when no metric was refused.\n\nEvery row value derived from a refused metric is null in that breakdown (purchaseValue and roas, or the matching actions and actionValues entries), never a number computed without it.\n","example":{"publisher_platform":["total_purchase","total_purchase_value","total_initiate_checkout_value"]}},"breakdownsRange":{"type":"object","description":"TikTok only, present when the requested range is longer than the 365 days TikTok serves per breakdown: the window the breakdowns cover (the last 365 days of the range). summary and daily still cover the full range.","properties":{"fromDate":{"type":"string","format":"date"},"toDate":{"type":"string","format":"date"}}}}}}},"AdAnalyticsResponse":{"type":"object","properties":{"backfillPending":{"type":"boolean","description":"Meta only. Present and true while historical data is being backfilled."},"ad":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"platform":{"type":"string"},"status":{"type":"string"},"currency":{"type":["string","null"],"description":"ISO 4217 code of the ad account that owns this ad (e.g. USD, THB, INR). All money values in `summary` and `daily` are in this currency. Null only on legacy ads synced before currency was persisted."}}},"analytics":{"type":"object","properties":{"summary":{"$ref":"#/components/schemas/AdMetrics"},"daily":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AdMetrics"},{"type":"object","properties":{"date":{"type":"string","format":"date"}}}]}},"breakdowns":{"type":"object","description":"Requested demographic breakdowns, keyed by dimension. Fetched live from the\nplatform per request and never stored, so these rows can carry fields the\nstored `summary` and `daily` series do not.\n\nLinkedIn rows carry `value` (the pivot URN), `name` (resolved label where\nLinkedIn provides one), the usual spend/impressions/clicks/ctr/cpc/cpm/engagement\nfigures, plus two reach fields:\n\n- `reach`: the segment's `approximateMemberReach`.\n- `audiencePenetration`: LinkedIn's own ratio of members reached to the size of\n  the targeted audience, passed through verbatim.\n\nLinkedIn withholds both below its audience privacy threshold, in which case the\nkeys are ABSENT rather than 0. `audiencePenetration` is available here only: it\nis not part of the stored metrics series.\n\nTikTok rows are keyed by TikTok's own dimension name (`country_code` for\n`country`, `platform` for `publisher_platform`). `placement` rows carry the\nlabel TikTok Ads Manager shows (`TikTok`, `TikTok Ad Network`, `News Feed App Series`)\nin `placement` and TikTok's API value (`PLACEMENT_TIKTOK`, `PLACEMENT_PANGLE`,\n`PLACEMENT_GLOBAL_APP_BUNDLE`) in `placementRaw`; a value without a known label\ncarries the raw value in both.\n\nA requested dimension with no data in the range is an empty array.\n","additionalProperties":{"type":"array","items":{"type":"object"}}},"unsupportedBreakdowns":{"type":"array","items":{"type":"string"},"description":"Requested breakdowns this platform cannot break down by (e.g. region on TikTok, any breakdown on Google). Absent when every requested breakdown is supported."},"breakdownHints":{"type":"object","additionalProperties":{"type":"string"},"description":"Guidance for some names in unsupportedBreakdowns, keyed by that name (e.g. placement on Meta points at publisher_platform and platform_position; platform_position on TikTok points at placement). Absent when no unsupported name has a hint."},"breakdownErrors":{"type":"array","description":"TikTok only: breakdowns the platform failed to return (rate limit, permission, rejected query). Each one is an empty array under breakdowns; summary and daily are unaffected. Absent when every breakdown answered.","items":{"type":"object","properties":{"breakdown":{"type":"string"},"message":{"type":"string","description":"The platform's error message."}}}},"breakdownDroppedMetrics":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"TikTok only: metric names TikTok refused for a breakdown, keyed by the requested breakdown (e.g. total_purchase and total_purchase_value have no relation to platform, ac or language). Absent when no metric was refused.\n\nEvery row value derived from a refused metric is null in that breakdown (purchaseValue and roas, or the matching actions and actionValues entries), never a number computed without it.\n","example":{"publisher_platform":["total_purchase","total_purchase_value","total_initiate_checkout_value"]}},"breakdownsRange":{"type":"object","description":"TikTok only, present when the requested range is longer than the 365 days TikTok serves per breakdown: the window the breakdowns cover (the last 365 days of the range). summary and daily still cover the full range.","properties":{"fromDate":{"type":"string","format":"date"},"toDate":{"type":"string","format":"date"}}}}}}},"AdMetrics":{"type":"object","properties":{"spend":{"type":"number"},"impressions":{"type":"integer"},"reach":{"type":"integer","description":"Unique people reached in the requested date range.\n\n- **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).\n- **Meta and TikTok fallback:** 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.\n- **Not additive (Meta and TikTok):** because reach is de-duplicated, neither daily values nor child nodes sum to the range total.\n- **LinkedIn:** the campaign's `approximateMemberReach`, de-duplicated by LinkedIn per day and summed over the range here, so it overcounts members reached on more than one day. LinkedIn withholds it below its audience privacy threshold, where it reads 0.\n- **Google, X, Pinterest and OpenAI:** 0 (reach not synced).\n\nFrequency (impressions / reach) is only meaningful for Meta and TikTok.\n"},"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 also reports modeled conversions, so values like 0.347 are normal. 0 for non-conversion campaigns or when no events have fired.\n\n- Meta: the ad set's Ads Manager Results, derived per ad set (see below).\n- Google: the account's tracked conversions.\n- X and LinkedIn: their reported website/lead conversions (added 2026-07).\n- Reddit: key conversions (`key_conversion_total_count`, added 2026-10-23; older days read 0).\n\nMeta uses the optimization goal's result: LEAD_GENERATION and QUALITY_LEAD = leads, CONVERSATIONS = messaging conversations started, APP_INSTALLS = installs, LANDING_PAGE_VIEWS = landing page views, LINK_CLICKS = link clicks, THRUPLAY = ThruPlays. REACH, IMPRESSIONS, POST_ENGAGEMENT and PAGE_LIKES report 0.\n\nOtherwise Meta uses the promoted_object event: custom_conversion_id when set, else custom_event_type, else PURCHASE.\n"},"allConversions":{"type":"number","description":"All conversions, including actions excluded from the Conversions column (Google metrics.all_conversions). 0 on platforms without the concept."},"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. Keys differ by platform, so branch on the ad's platform when interpreting them. Empty object when no actions are reported.\n\n- Meta: raw Insights action_type keys (link_click, offsite_conversion.fb_pixel_purchase, onsite_conversion.lead_grouped, ...), covering both engagement and conversion events.\n- Meta newer standard events (Schedule, SubmitApplication, Contact, StartTrial, Subscribe and the like) come only from Meta's `conversions` insight field, under keys such as schedule_total, schedule_website or offsite_schedule_add_<dataset>.\n- Since 2026-11-03 every `conversions` key that `actions` lacks is added here, rounded per key, and its `conversion_values` value to `actionValues`. A key both fields report keeps its `actions` value.\n- Days synced before 2026-11-03 lack those keys until re-fetched. Each sync restates the last 30 days.\n- TikTok: conversion events plus the paid-engagement family (follow, post_reaction for paid likes, comment, share). Follow is how FOLLOWERS-goal campaigns report their result.\n- TikTok website (pixel) events: complete_payment (website purchase, counted in `conversions` by SHOPPING-optimised campaigns), place_order, initiate_checkout, add_to_cart, view_content, lead (website form submissions plus TikTok instant-form leads).\n- TikTok place_order is Place an Order, the website purchase of pixels set up with the legacy ON_WEB_ORDER event. It is absent from days synced before this metric was added until the ad is re-synced.\n- TikTok app events: purchase, view_content (added to the website count).\n- TikTok history: website add_to_cart, initiate_checkout, complete_payment and lead were missing before 2026-10-08 (TikTok rejected the metric names we requested). Each sync re-fetches only the last 7 days, so older days lack them until the ad is re-synced from scratch.\n- X: conversion types (purchase, sign_up, site_visit, download, custom).\n- LinkedIn: conversion types (post_click, post_view, lead_gen) plus `video_view`. It carries LinkedIn's `videoViews` under the key every other platform uses, so it feeds `engagementBreakdown.videoViews` too. It is an engagement, NOT a conversion, and is excluded from `conversions`.\n- Google: returns {} (its per-action names aren't synced per ad).\n","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. Meta and TikTok; other platforms return {}. Same history note as `actions`.\n\nSame keying as `actions`: 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 it to compute revenue-per-event (e.g. avg purchase value).\n\nTikTok: the value TikTok attributes to each key of `actions`, present only when the advertiser sends a value with the event. Keys: purchase and view_content from app events; complete_payment, initiate_checkout, add_to_cart, view_content and lead from the website pixel.\n\ninitiate_checkout and add_to_cart values are basket values, not revenue. Revenue is complete_payment or place_order (website) and purchase (app).\n","example":{"offsite_conversion.fb_pixel_purchase":2456.78,"offsite_conversion.fb_pixel_add_to_cart":980.5}},"purchaseValue":{"type":"number","description":"Convenience sum of purchase-type action values, in ad-account native currency. 0 when the campaign has no purchase event configured.\n\nMeta: picked from `actionValues` for the ad set promoted_object event (custom conversion, custom_event_type, else PURCHASE). It matches `conversions` for conversion-optimized ad sets. When the optimization goal reports a different result (LINK_CLICKS, LANDING_PAGE_VIEWS, ...) it stays on the promoted event, so ROAS keeps its purchase basis.\n\n- TikTok: app purchase value plus website complete-payment value (from 2026-10-08), or the Place an Order value when that is larger. They are never summed, since a pixel can fire both for one sale. Days synced before each was added carry the app value only until the ad is re-synced.\n- Google: `conversions_value` of every primary conversion action.\n- Pinterest: checkout value.\n- LinkedIn: `conversionValueInLocalCurrency`, the advertiser-defined value of every conversion (days synced before 2026-10-23 report 0).\n- Reddit: `conversion_purchase_total_value` (same history note).\n- Other platforms report 0.\n"},"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."},"costPerAction":{"type":"object","additionalProperties":{"type":"number"},"description":"Derived `spend / actions[type]` for every action type with a non-zero count, in ad-account native currency. Same keys as `actions`.\n\n- Rounded to 4 decimals, because cheap actions cost well under a cent.\n- Recomputed from summed spend + counts at every rollup level.\n- Empty object when spend is 0 or no actions are reported.\n","example":{"link_click":0.1052,"offsite_conversion.fb_pixel_purchase":4.0114}},"outboundClicks":{"type":"integer","description":"Clicks leading off Meta's surfaces to the advertiser's destination. Meta-only; other platforms report 0."},"outboundClicksCtr":{"type":"number","description":"Derived `outboundClicks / impressions * 100`, recomputed from sums at every rollup level."},"inlineLinkClicks":{"type":"integer","description":"In-session link clicks. Differs from the attributed `link_click` count in `actions`/`engagementBreakdown.linkClicks`, which uses the attribution window. Meta-only."},"inlineLinkClickCtr":{"type":"number","description":"Derived `inlineLinkClicks / impressions * 100`, recomputed from sums at every rollup level."},"uniqueClicks":{"type":"integer","description":"People who clicked at least once. NOT additive: summed across days/children it overcounts people who clicked on multiple days or ads, so treat rollups as an upper bound (same caveat as `reach`). Meta-only."},"uniqueCtr":{"type":"number","description":"Derived `uniqueClicks / impressions * 100` (NOT Meta's reach-based unique_ctr). Inherits the non-additivity caveat of `uniqueClicks`."},"videoPlayActions":{"type":"integer","description":"Number of times the video started playing, summed over the date range and across children at ad-set/campaign level. 0 for non-video ads.\n\nSources: Meta `video_play_actions`, TikTok `video_play_actions`, X `video_content_starts`, Reddit `video_started`, Pinterest `TOTAL_VIDEO_P0_COMBINED`.\n\n**X, Reddit and Pinterest history**: added 2026-10-23, and their syncs only re-fetch recent days, so older days read 0 on every X, Reddit and Pinterest video field.\n"},"video30SecWatchedActions":{"type":"integer","description":"Views of at least 30 seconds (or to the end, for shorter videos). Sources: Meta `video_30_sec_watched_actions`, Google `video_trueview_views` (a TrueView view: 30 seconds, the whole video if shorter, or an interaction; Google history note: added 2026-10-23, older days read 0)."},"videoThruplayWatchedActions":{"type":"integer","description":"ThruPlays (watched to completion, or at least 15 seconds). Sources: Meta `video_thruplay_watched_actions` (Meta only)."},"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). Sources: Meta `video_p25_watched_actions`, TikTok `video_views_p25`, X `video_views_25`, Reddit `video_watched_25_percent`, Google `video_quartile_p25_rate` x impressions, Pinterest `TOTAL_VIDEO_P25_COMBINED`."},"videoP50WatchedActions":{"type":"integer","description":"Views reaching 50% of the video's length. Sources: Meta `video_p50_watched_actions`, TikTok `video_views_p50`, X `video_views_50`, Reddit `video_watched_50_percent`, Google `video_quartile_p50_rate` x impressions, Pinterest `TOTAL_VIDEO_P50_COMBINED`."},"videoP75WatchedActions":{"type":"integer","description":"Views reaching 75% of the video's length. Sources: Meta `video_p75_watched_actions`, TikTok `video_views_p75`, X `video_views_75`, Reddit `video_watched_75_percent`, Google `video_quartile_p75_rate` x impressions, Pinterest `TOTAL_VIDEO_P75_COMBINED`."},"videoP95WatchedActions":{"type":"integer","description":"Views reaching 95% of the video's length. Sources: Meta `video_p95_watched_actions`, Pinterest `TOTAL_VIDEO_P95_COMBINED`."},"videoP100WatchedActions":{"type":"integer","description":"Views reaching 100% of the video's length. Sources: Meta `video_p100_watched_actions`, TikTok `video_views_p100`, X `video_views_100`, Reddit `video_watched_100_percent`, Google `video_quartile_p100_rate` x impressions, Pinterest `TOTAL_VIDEO_P100_COMPLETE`."},"video2SecWatchedActions":{"type":"integer","description":"Plays of at least 2 seconds, replays excluded. Hook rate = video2SecWatchedActions / impressions. Sources: TikTok `video_watched_2s` (TikTok only; Meta's closest field, 2-second continuous plays, is not synced). TikTok history note: added 2026-10, and each sync re-fetches only the last 7 days, so older days read 0."},"video6SecWatchedActions":{"type":"integer","description":"Plays of at least 6 seconds, replays excluded. Hold rate = video6SecWatchedActions / video2SecWatchedActions. Sources: TikTok `video_watched_6s` (TikTok only). Same history note as `video2SecWatchedActions`."},"video6SecFocusedViews":{"type":"integer","description":"TikTok's 6-second focused views: plays of at least 6 seconds (or to the end, for shorter videos) or with an interaction in the first 6 seconds, so it is at least `video6SecWatchedActions`. Sources: TikTok `engaged_view` (TikTok only). Same history note as `video2SecWatchedActions`."},"videoAvgTimeWatchedActions":{"type":"number","description":"Average seconds watched per play. Aggregated over date ranges and across children as a play-weighted average (total watch time / total plays), never a plain average of averages. Sources: Meta `video_avg_time_watched_actions`, TikTok `average_video_play`."},"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 (ThruPlay is Meta-only)."},"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.\n\nMeta reports one event under several action types at once (`offsite_conversion.fb_pixel_purchase`, `omni_purchase`, `purchase`, …). Each field takes the FIRST family member present rather than summing them, which makes these counts safe to add up. Summing the raw `actions` keys yourself double or triple counts.\n\nThe same priority order backs `conversions`, so a purchase-optimised campaign reports the identical number in `conversions` and `funnel.purchases`.\n\nEvery field is 0 when that step never fired. At ad-set and campaign level each step is summed from its per-ad values.\n\n- Meta ads: populated.\n- TikTok, from 2026-10-08: contentViews, cartAdds, checkoutsInitiated, purchases (app purchases, else website complete payments, else Place an Order) and leads. The other steps stay 0.\n- Other platforms report a different action taxonomy and generally leave these at 0 (read `actions` for those).\n","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. Pair with `purchaseValue` for revenue.\n\n**Meta** reports one purchase under several action types, so this takes the FIRST present, in this order, never a sum: `offsite_conversion.fb_pixel_purchase`, `omni_purchase`, `app_custom_event.fb_mobile_purchase`, `onsite_conversion.purchase`, `purchase`.\n\nIt always counts purchases, whatever the ad set optimizes for. `conversions` instead follows the ad set's optimization event (PURCHASE when none is named), so the two can differ on any other goal.\n\n**TikTok:** app purchases (`purchase`), else website complete payments (`complete_payment`), else Place an Order (`place_order`).\n"},"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."},"schedules":{"type":"integer","description":"Booked appointments (Meta `Schedule` pixel event). Pair with `spend` for cost per booked meeting.\n\n**Meta** reports Schedule in its `conversions` insight field, never in `actions`. This takes the FIRST present of `offsite_conversion.fb_pixel_schedule`, `omni_schedule`, `app_custom_event.fb_mobile_schedule`, `onsite_conversion.schedule`, `schedule`, `schedule_total`, `schedule_mobile_app`, `schedule_website`, `schedule_offline`. With none of those, a single `offsite_schedule_add_<dataset>` key counts. Two such keys (two datasets) leave it at 0, since one booking can reach both.\n\nAdded 2026-11-03. Days synced before then read 0 until re-fetched: each sync restates the last 30 days.\n"}}},"AdEngagementCounts":{"type":"object","description":"The single `engagement` total, split into the interactions behind it.\n\n`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 for a specific interaction, and `engagement` only as the coarse total it has always been.\n\n**Platforms**: populated for Meta and, since 2026-08, TikTok (`reactions` = paid likes, `comments`, `shares`; TikTok's `follow` count lives in `actions.follow`, not here). Other platforms leave these at 0.\n\n**TikTok history**: these splits were added in 2026-08, and only the last 7 days are re-fetched on each sync (a stopped ad keeps syncing until its last delivery day is 7 days old). Days stored before the rollout keep 0s here. Spend, impressions, clicks and conversions are not affected.\n","properties":{"postEngagement":{"type":"integer","description":"Meta's own post-engagement total (`post_engagement`). Meta-only."},"pageEngagement":{"type":"integer","description":"Meta's own page-engagement total (`page_engagement`). Meta-only."},"reactions":{"type":"integer","description":"Reactions on the ad's post (`post_reaction`). For TikTok these are its paid likes."},"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`; TikTok under `share`."},"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":"Video views, from the `video_view` action. Meta counts a 3-second view; LinkedIn's own `videoViews` threshold (2 continuous seconds, or 25% of the video) lands under the same key, so compare across platforms with care. 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 count in the sibling `inlineLinkClicks` field."}}},"AdDailyMetrics":{"description":"One day of metrics: the 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`.\n\nRate 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.\n\nExceptions:\n\n- `reach`: on Meta and TikTok the aggregated total is de-duplicated across the range, so daily reach does not sum to it.\n- `videoAvgTimeWatchedActions`: do NOT sum or plain-average it across days. The range value is the play-weighted average of the daily values.\n","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"]},"AdActivationStatus":{"type":"string","enum":["ACTIVE","PAUSED"],"description":"Request-side publish switch for `adStatus` on ad creation endpoints only (`status`, `campaignStatus` and `adSetStatus` carry their own inline ACTIVE/PAUSED enum there; the status-update endpoints are a separate lowercase `active`/`paused` enum). Distinct from `AdStatus` (the platform-reported delivery status returned on reads)."},"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\nTikTok's agency container: one BC owns N advertisers (ad accounts). Most solo\nadvertisers don't have one; the agency token uses BCs to roll up multi-client access.\n","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.\n`null` when the BC asset walk returned empty or failed (typical for\nagency apps without full BC asset read scope), distinct from `0`,\nwhich would imply the BC genuinely has no advertisers.\n","example":23}}},"ValueRuleCriterion":{"type":"object","additionalProperties":false,"required":["criteriaType","operator","criteriaValues","criteriaValueTypes"],"description":"One matching condition inside a value rule. `criteriaValues` and `criteriaValueTypes`\nare POSITIONALLY paired: same length, same order.\n","properties":{"id":{"type":"string","description":"Platform criterion id. Echo it on `PUT` to KEEP this criterion, omit it to CREATE a\nnew one. A criterion left out of the array entirely is DELETED.\n"},"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,\nPHONE_CALL, WEBSITE) is accepted even though Meta's own enum table omits it.\n"},"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.\n\n- `AGE`: 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`).\n- `LOCATION`: Targeting-Search keys. A two-letter country code for `LOCATION_COUNTRY`, a numeric key for region / city / comScore market.\n- `AUDIENCE_LABEL`: 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.\n"},"criteriaValueTypes":{"type":"array","minItems":1,"items":{"type":"string"},"description":"One entry per `criteriaValues` entry, in the same order. The literal `\"NONE\"` for\nevery criteriaType except `LOCATION`, which uses `LOCATION_COUNTRY`,\n`LOCATION_REGION`, `LOCATION_CITY` or `LOCATION_COMSCORE_MARKET` and MAY mix them\nwithin one criterion. `LOCATION_DMA` was replaced by `LOCATION_COMSCORE_MARKET` on\n2026-06-22 and is rejected by this API.\n"}}},"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\nrule adjusts the bid for an overlapping audience, so the order is semantic.\n","properties":{"id":{"type":"string","description":"Platform rule id. Echo it on `PUT` to KEEP this rule, omit it to CREATE a new one.\nA rule left out of the array entirely is DELETED.\n"},"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.\n0 is out of range on both.\n"},"status":{"type":"string","description":"Meta returns `ACTIVE` here but documents no enum for the field. Treat it as a\npassthrough: echo whatever the `GET` returned, and do not synthesize values.\n"},"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\n`valueRuleSetId`. Limits: 6 sets per ad account, 10 rules per set, 4 criteria per rule.\n","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)\noverrides campaign-level. Cross-field rules:\n  - `LOWEST_COST_WITHOUT_CAP` (default): auto-bid, forbids `bidAmount` and `roasAverageFloor`.\n  - `LOWEST_COST_WITH_BID_CAP` / `COST_CAP`: require `bidAmount` (whole currency units).\n  - `LOWEST_COST_WITH_MIN_ROAS`: requires `roasAverageFloor` (decimal multiplier, 2.0 = 2.0x).\nSource: facebook-business-sdk-codegen api_specs/specs/enum_types.json (`AdSet_bid_strategy`,\n`Campaign_bid_strategy`).\n"},"GoogleAdsHierarchyClient":{"type":"object","description":"A Google Ads account inside a manager tree.","properties":{"customerId":{"type":"string","description":"Native Google Ads customer id, digits only."},"name":{"type":["string","null"],"description":"Null for a pending invitation."},"currency":{"type":["string","null"]},"timeZone":{"type":["string","null"]},"manager":{"type":"boolean","description":"True for a sub-manager account."},"testAccount":{"type":"boolean"},"hidden":{"type":"boolean","description":"Hidden in the manager's Google Ads UI."},"level":{"type":"integer","description":"Distance from the root (1 = direct client of the root)."},"status":{"type":["string","null"],"description":"Google customer status: ENABLED, CANCELED, SUSPENDED or CLOSED. Null for a pending invitation."},"parentCustomerId":{"type":["string","null"],"description":"Direct manager of this account. Null only when more than 50 managers under the root were skipped."},"managerLinkId":{"type":["string","null"],"description":"Id of the link to the parent, used by PATCH /v1/ads/accounts/manager-links."},"linkStatus":{"type":["string","null"],"enum":["ACTIVE","PENDING",null]}}},"GoogleAdsManagerLink":{"type":"object","properties":{"managerCustomerId":{"type":"string"},"clientCustomerId":{"type":"string"},"managerLinkId":{"type":["string","null"],"description":"Null on a validateOnly invitation, where Google creates nothing."},"status":{"type":"string","enum":["PENDING","ACTIVE","REFUSED","CANCELED","INACTIVE"],"description":"Status the link has after this call."},"validateOnly":{"type":"boolean"}}},"GoogleAdsAccessRole":{"type":"string","enum":["ADMIN","STANDARD","READ_ONLY","EMAIL_ONLY"],"description":"ADMIN manages the account and its users, STANDARD edits campaigns, READ_ONLY views them, EMAIL_ONLY only receives the account's emails."},"GoogleAdsUserAccessInvitation":{"type":"object","properties":{"invitationId":{"type":"string"},"emailAddress":{"type":"string"},"accessRole":{"type":"string","enum":["ADMIN","STANDARD","READ_ONLY","EMAIL_ONLY","UNKNOWN"]},"status":{"type":"string","enum":["PENDING","DECLINED","EXPIRED","UNKNOWN"]},"createdAt":{"type":["string","null"],"description":"Google's creation time, yyyy-MM-dd HH:mm:ss.ssssss in the account's time zone."}}},"GoogleAdsUserAccessInvitationResult":{"type":"object","properties":{"customerId":{"type":"string"},"emailAddress":{"type":"string"},"accessRole":{"$ref":"#/components/schemas/GoogleAdsAccessRole"},"status":{"type":"string","enum":["PENDING","PENDING_APPROVAL"],"description":"PENDING once the email is sent; PENDING_APPROVAL while Google waits for a second admin's multi-party approval."},"invitationId":{"type":["string","null"],"description":"Null on validateOnly and while the invitation awaits multi-party approval."},"multiPartyAuthReviewId":{"type":["string","null"],"description":"Google's multi-party approval review id when status is PENDING_APPROVAL."},"validateOnly":{"type":"boolean"}}},"GoogleAdsUserInvitationApproval":{"type":"object","properties":{"multiPartyAuthReviewId":{"type":"string","description":"Pass to DELETE /v1/ads/accounts/user-invitations/pending-approvals to withdraw the request."},"emailAddress":{"type":["string","null"],"description":"Invited email address."},"accessRole":{"type":"string","enum":["ADMIN","STANDARD","READ_ONLY","EMAIL_ONLY","UNKNOWN"]},"requestUserEmail":{"type":["string","null"],"description":"Google user who sent the invitation. Only this user can withdraw it."},"createdAt":{"type":["string","null"],"description":"Google's creation time, yyyy-MM-dd HH:mm:ss.ssssss in the account's time zone."}}},"GoogleTargetImpressionShare":{"type":"object","additionalProperties":false,"required":["location","percent","maxCpc"],"description":"Google only. Target impression share bidding (Search campaigns only): Google sets bids so the ads show in `location` for `percent` of eligible impressions.","properties":{"location":{"type":"string","enum":["ANYWHERE_ON_PAGE","TOP_OF_PAGE","ABSOLUTE_TOP_OF_PAGE"]},"percent":{"type":"number","exclusiveMinimum":0,"maximum":100,"description":"Target share of impressions, in percent (65 = 65%). Sent to Google as location_fraction_micros (1% = 10,000)."},"maxCpc":{"type":"number","exclusiveMinimum":0,"description":"Max CPC bid limit, in the account's currency units. Google requires it."}}},"GoogleManualCpc":{"type":"object","additionalProperties":false,"required":["maxCpc"],"description":"Google Search and Display only. Manual CPC bidding. Enhanced CPC is not offered: Google no longer lets Search and Display campaigns enable it. Exclusive with every other strategy field.","properties":{"maxCpc":{"type":"number","exclusiveMinimum":0,"description":"Max CPC of the ad groups, in the account's currency units: set on the ad group created with the campaign, and on every ad group of the campaign when an update switches it to Manual CPC. Google gives an ad group without one a 0.01 bid."}}},"GoogleNetworkSettings":{"type":"object","additionalProperties":false,"minProperties":1,"description":"Google Search campaigns only. Which networks the campaign serves on besides Google Search. When omitted at creation, search partners are ON and the Display Network is OFF (the defaults Zernio has always used); on an update only the fields sent change.","properties":{"searchPartners":{"type":"boolean","description":"campaign.network_settings.target_search_network"},"displayNetwork":{"type":"boolean","description":"campaign.network_settings.target_content_network (Search with Display expansion)"}}},"PortfolioBidStrategy":{"type":"object","description":"A Google Ads portfolio bid strategy: a named bidding strategy shared across campaigns, with its R.130 report metrics over the queried date range.","properties":{"id":{"type":"string","description":"Numeric bid strategy id; pass as portfolioBidStrategyId or in the {strategyId} path."},"name":{"type":"string"},"type":{"type":"string","enum":["TARGET_CPA","TARGET_ROAS","MAXIMIZE_CONVERSIONS","MAXIMIZE_CONVERSION_VALUE","TARGET_IMPRESSION_SHARE"]},"status":{"type":"string","description":"ENABLED or REMOVED."},"campaignCount":{"type":"integer","description":"Number of campaigns currently attached."},"clicks":{"type":"integer"},"cost":{"type":"number","description":"Cost in the account's currency units (converted from micros)."},"costPerConversion":{"type":"number","description":"Cost per conversion in the account's currency units."},"impressions":{"type":"integer"},"averageCpc":{"type":"number","description":"Average CPC in the account's currency units."},"conversions":{"type":"number"},"targetCpa":{"type":["number","null"],"description":"Current target, in the account's currency units. Null for a ROAS-family type (TARGET_ROAS, MAXIMIZE_CONVERSION_VALUE), or a Maximize type with no target set. Pre-fills the edit form's target field."},"targetRoas":{"type":["number","null"],"description":"Current target as a decimal multiplier (2.0 = 2.0x). Null for a CPA-family type (TARGET_CPA, MAXIMIZE_CONVERSIONS), or a Maximize type with no target set."},"targetImpressionShare":{"description":"Current target for a TARGET_IMPRESSION_SHARE strategy, null for every other type.","oneOf":[{"$ref":"#/components/schemas/GoogleTargetImpressionShare"},{"type":"null"}]}}},"CampaignBidding":{"type":"object","description":"A Google campaign's current bidding, mapped onto the same triplet PUT /v1/ads/campaigns/{campaignId} accepts.","properties":{"channel":{"type":"string","enum":["SEARCH","DISPLAY"],"description":"campaign.advertising_channel_type. COST_CAP's underlying Google field differs by channel; see bidStrategy on PUT."},"biddingStrategyType":{"type":"string","description":"Google's raw enum: MAXIMIZE_CONVERSIONS, TARGET_CPA, MAXIMIZE_CONVERSION_VALUE, TARGET_ROAS, TARGET_SPEND, MANUAL_CPC, TARGET_IMPRESSION_SHARE, or another Google adds later."},"bidSpec":{"type":["object","null"],"description":"Null when the campaign is on a strategy PUT does not model (Manual CPC, Target Impression Share, ...); show biddingStrategyType instead in that case.","properties":{"bidStrategy":{"$ref":"#/components/schemas/BidStrategy"},"bidAmount":{"type":"number","description":"Whole currency units. Present for COST_CAP and LOWEST_COST_WITH_BID_CAP, and omitted when the campaign is on a bare TARGET_SPEND with no CPC ceiling set."},"roasAverageFloor":{"type":"number","description":"Decimal ROAS multiplier (2.0 = 2.0x). Present for LOWEST_COST_WITH_MIN_ROAS."},"portfolioBidStrategyId":{"type":"string","description":"Present alone (bidStrategy omitted) when the campaign is on a portfolio strategy; see portfolio."}}},"portfolio":{"type":["object","null"],"description":"Set only when the campaign is on a portfolio bid strategy (campaign.bidding_strategy); null otherwise.","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"cachedAt":{"type":["string","null"],"format":"date-time","description":"When this data was fetched from Google. Null when it was never served from cache."},"stale":{"type":"boolean","description":"True when Google's daily API quota was exhausted and this is the last successful fetch, not a live read."}}},"AdCampaignBudget":{"allOf":[{"$ref":"#/components/schemas/AdBudget"},{"type":"object","properties":{"amountMicros":{"type":"string","pattern":"^\\d+$","description":"Google only. Exact decimal micros; DAILY uses amount_micros and CUSTOM_PERIOD uses total_amount_micros."},"explicitlyShared":{"type":["boolean","null"],"description":"Google only. True for a shared budget; null when unavailable. Shared writes require allowSharedBudgetUpdate=true; unknown sharing status cannot be overridden."},"resourceName":{"type":["string","null"],"description":"Google only. campaign_budget.resource_name, or null when unavailable."},"deliveryMethod":{"type":["string","null"],"description":"Google only. campaign_budget.delivery_method, typically STANDARD, or null when unavailable."}}}]},"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"]}}},"AdPromotedObject":{"type":"object","description":"What the ad optimises against. Behaviour depends on the platform. Platforms other than Meta, TikTok, OpenAI and Reddit ignore `promotedObject` entirely.\n\n**Meta**: forwarded to the ad set's `promoted_object` (snake-cased).\n\n- For `goal: app_promotion`, also sent on the campaign only when `isSkadnetworkAttribution: true`; plain Android app installs keep it on the ad set only. POST /v1/ads/campaigns forwards it on Meta only for that SKAN flag.\n- Required when the ad-set optimization_goal points at a specific event/page/app. Without it Meta rejects the ad set with `error_subcode: 1815430` \"Please select a promoted object for your ad set\".\n- `goal: conversions` / `lead_conversion` (OFFSITE_CONVERSIONS): requires `pixelId` + `customEventType`, or `customConversionId` for a Custom Conversion (it carries its own event). For a pixel CUSTOM event you named in CAPI/Events Manager, send `customEventType: OTHER` + `customEventStr` with the event name.\n- `goal: app_promotion` (APP_INSTALLS): requires `applicationId` + `objectStoreUrl`.\n- `goal: lead_generation` (LEAD_GENERATION): `pageId` is auto-filled from the connected Page when omitted.\n- Other Meta goals (engagement, traffic, awareness, video_views) ignore this field. The remaining `promotedObject.*` fields are Meta-only.\n\n**TikTok**: used by `goal: conversions` and the Smart+ goals (`smartPlus: true`).\n\n- `pixelId` maps to the ad group's `pixel_id`. Required: a website-conversion ad group without a pixel is rejected with `40002: Please select a pixel`.\n- `customEventType` maps to the ad group's `optimization_event`. Optional on regular conversions, required on Smart+. See the `customEventType` field for valid codes.\n- `applicationId` (Smart+ `goal: app_promotion` only) maps to `app_id`: an app registered on the TikTok Ads account (Assets → Events → App Events). Install optimization needs the app's MMP tracking configured.\n\n**OpenAI (ChatGPT) Ads**: `goal: conversions` only, on POST /v1/ads/create and POST /v1/ads/campaigns. `customEventType` picks the conversion event (sent as the campaign's `conversion_event_setting_ids`); any other `promotedObject` field returns 400.\n\n**Reddit Ads**: every ad group gets a pixel, whatever the goal.\n\n- `pixelId` (or `tracking.pixelId`) picks it; when omitted, the ad account's first pixel is used. No pixel on the account returns 422 (create one in Reddit Ads Manager); a `pixelId` not on the account returns 400.\n- `goal: conversions` requires `customEventType`. `goal: lead_generation` optimizes toward the pixel's Lead event.\n- Reddit only optimizes toward an event the pixel has already received, otherwise 422 `invalid_resource_state`. Fire it from your site or send it with POST /v1/ads/conversions first.\n","properties":{"pixelId":{"type":"string","description":"Pixel ID.\n\n- **Meta:** Facebook Pixel ID, required for `goal: conversions`. Requires `customEventType` alongside it: Meta rejects any promoted_object carrying `pixel_id` without `custom_event_type` (error_subcode 1885014), even when `customConversionId` is also present.\n- **TikTok:** TikTok Pixel ID, required for `goal: conversions`.\n- **Reddit:** Reddit pixel ID (e.g. `a2_abc123`), optional on every goal (see above).\n\nTo discover the pixels an ad account can use, call `GET /v1/accounts/{accountId}/tracking-tags?adAccountId=act_...` (each entry carries `kind` and `ownerAdAccountId`) or `GET /v1/accounts/{accountId}/conversion-destinations`.\n\nThis differs from `GET /v1/ads/{adId}/tracking-tags`, which reads an ad's click-URL params (`url_tags`), not pixels.\n"},"customEventType":{"type":"string","description":"The event the campaign/ad group optimises against.\n\n**Meta:** a standard event like `PURCHASE`, `LEAD`, `COMPLETE_REGISTRATION`, `ADD_TO_CART`. Uppercased internally, so any case works. Required for `goal: conversions`.\n\n**TikTok:** an `optimization_event` code (UPPER_SNAKE, not Meta's vocabulary and not PascalCase), OR the exact event name shown in TikTok Events Manager (auto-resolved to its code). Optional for `goal: conversions`.\n\nIt must be an event type your TikTok Pixel tracks; custom events are not optimizable. On rejection the error lists the event types your pixel tracks. Current taxonomy (`ON_WEB_ORDER` is deprecated):\n\n- `SHOPPING`: Purchase\n- `ON_WEB_CART`: Add to Cart\n- `INITIATE_ORDER`: Initiate Checkout\n- `FORM`: Lead\n- `ON_WEB_REGISTER`: Complete Registration\n- `ON_WEB_DETAIL`: View Content\n\n**OpenAI (ChatGPT) Ads:** a conversion event from `GET /v1/accounts/{accountId}/conversion-destinations` (`conversionEvents[]`), given as its `id` (exact), its `eventType` (e.g. `order_created`) or its `name` (e.g. `Purchase`), both case-insensitive. It must be `optimizable` (active and not custom).\n\nAn unknown, archived or custom event returns a 400 listing the account's optimizable events. A type or name shared by several optimizable events returns a 400 asking for the id. `validateOnly: true` runs the same check and names the resolved event in its `message`.\n\nOptional for OpenAI: when omitted, the campaign optimizes for the first optimizable event in OpenAI's own list order, which is the most recently created one.\n\n**Reddit:** required for `goal: conversions` (400 without it). Any case. The pixel must already have received the event (422 otherwise). Accepted values:\n\n- `PURCHASE`, `LEAD`, `ADD_TO_CART`, `PAGE_VISIT`\n- `COMPLETE_REGISTRATION` or `SIGN_UP` (both sent as Reddit's SIGN_UP)\n- `VIEW_CONTENT` or `CONTENT_VIEW` (both sent as PAGE_VISIT)\n"},"customEventStr":{"type":"string","description":"Meta only. Pixel custom-event name to optimise against (Meta's `custom_event_str`), exactly as it appears in Events Manager and your CAPI payloads (case-sensitive, not uppercased). Same as picking a custom event in Ads Manager's conversion-event dropdown.\n\nRequires `customEventType: OTHER`, and `OTHER` requires this field (400 either way). For rule-based Custom Conversions use `customConversionId` instead.\n"},"pageId":{"type":"string","description":"Facebook Page ID. Used by `goal: lead_generation`. Auto-filled from the\nconnected Page when omitted.\n"},"applicationId":{"type":"string","description":"App ID. Required for `goal: app_promotion`."},"objectStoreUrl":{"type":"string","format":"uri","description":"App Store / Play Store listing URL. Required for `goal: app_promotion`."},"customConversionId":{"type":"string","description":"Custom Conversion ID, when optimising against one instead of a standard\nevent. Accepted alone by this API, without `pixelId` or `customEventType`.\nIf `pixelId` is also sent, `customEventType` is still required on the\npromoted_object (Meta rejects `pixel_id` without `custom_event_type`,\nerror_subcode 1885014).\n"},"productCatalogId":{"type":"string","description":"Optional catalog ID. If supplied with productSetId, the set must belong to this catalog (checked by Zernio when the Meta login carries catalog_management, by Meta otherwise). A catalog ID cannot replace productSetId."},"productSetId":{"type":"string","description":"Meta product SET ID, for example from GET /v1/ads/catalogs/{catalogId}/product-sets. Creating catalog ads needs only ads_management on the Meta login, not catalog_management.\n\n**Where it goes.** With goal catalog_sales, on the ad set's promoted_object and on the template creative. With goal traffic, or with adSetId, only on the creative.\n\n**Validation:**\n\n- Zernio reads the set before creation and returns a 400 naming promotedObject.productSetId when Meta rejects the ID outright.\n- When Meta answers that the login lacks permission to read it (common without catalog_management, even for a set a live ad set already uses), Zernio leaves the check to Meta's own create validation, which rejects an unusable set or a catalog ID with the same 400.\n- When the login can also read the set's catalog (catalog_management), a mismatch with productCatalogId returns a 400 naming promotedObject.productCatalogId. Otherwise Meta judges the catalog match.\n\nWith validateOnly and a new campaign, Meta cannot dry-run the set inside the ad set, so the adSet result carries a reason. Pass existingCampaignId to dry-run it in full.\n"},"offlineConversionDataSetId":{"type":"string","description":"Meta only. Offline event set (dataset) to optimise toward. Post-merger these are datasets: the id is the dataset id (for pixel-backed datasets, the pixel id)."},"whatsappPhoneNumber":{"type":"string","description":"Meta only. WhatsApp number on messaging-destination ad sets."}},"additionalProperties":false},"TargetingSpec":{"type":"object","description":"Normalized, platform-agnostic ad-targeting spec. Every field is optional; an empty object targets the platform's default broadest audience.\n\nField 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.\n\n**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.\n\n**Portable fields** carry across platforms: `countries`, `ageMin`/`ageMax`, `gender`, `incomeTier`, `languages`.\n\nFields a platform cannot honour are rejected on create, boost and targeting update with `INVALID_FIELD_VALUE` naming the offending field (never silently dropped).\n","properties":{"userOs":{"type":"array","minItems":1,"items":{"type":"string","minLength":1},"description":"Meta only. Operating systems and version ranges, such as iOS_ver_14.0_and_above or Android. Emitted as user_os. May also be supplied inside targeting."},"userDevice":{"type":"array","minItems":1,"items":{"type":"string","minLength":1},"description":"Meta only. Device models such as iPhone. Emitted as user_device. May also be supplied inside targeting."},"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. An entry may also be that id as a plain string (`\"20321\"` is `{ key: \"20321\" }`).","items":{"oneOf":[{"type":"string"},{"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). An entry may also be the city id as a plain string (`\"1006410\"` is `{ key: \"1006410\" }`).","items":{"oneOf":[{"type":"string"},{"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"}}}},"countryGroups":{"type":"array","description":"Meta only. Continents and trade blocs (`geo_locations.country_groups`),\nfor targeting a whole region without listing its countries. Combines\nwith `countries` rather than replacing it, and is also accepted under\n`excludedLocations`. Discoverable via\n`GET /v1/ads/targeting/search?dimension=geo&geoType=country_group`.\n","items":{"type":"string","enum":["africa","asia","europe","north_america","south_america","oceania","central_america","caribbean","eea","euro_area","nafta","mercosur","afta","apec","gcc","cisfta","emerging_markets","itunes_app_store","android_free_store","android_paid_store"]}},"customLocations":{"type":"array","description":"Point-radius (lat/lng) targeting (Meta custom_locations / Google proximity). Honoured on Meta and Google; ignored on platforms without radius support.","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.\n\n- Meta (excluded_geo_locations): excluded cities can carry a radius catchment, and excluded custom (lat/lng) pins are supported.\n- Google (Search, Display, Performance Max): excludes countries, regions, cities and zips as negative location criteria. countryGroups, places, neighborhoods, customLocations and a city radius return 400.\n- Google Demand Gen: returns 400 for any exclusion.\n","properties":{"countries":{"type":"array","items":{"type":"string"}},"countryGroups":{"type":"array","description":"Meta only. Continents and trade blocs to exclude (`excluded_geo_locations.country_groups`).","items":{"type":"string","enum":["africa","asia","europe","north_america","south_america","oceania","central_america","caribbean","eea","euro_area","nafta","mercosur","afta","apec","gcc","cisfta","emerging_markets","itunes_app_store","android_free_store","android_paid_store"]}},"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,"description":"Minimum age.\n\n- Applied on Meta, TikTok, Pinterest, LinkedIn, X and Google Search/Display (Google excludes the age ranges outside the request).\n- Rejected with 400 on OpenAI, Reddit and Google Performance Max / Demand Gen.\n\nEach platform clamps to its own range:\n\n- Meta and Pinterest: effectively cap at 65 (65 = 65+).\n- Pinterest: no under-18 bucket, so an ageMin below 18 starts at 18.\n- TikTok: maps up to 100.\n- LinkedIn: rounds out to its buckets (18-24, 25-34, 35-54, 55+) and has no under-18 audience.\n- X: rounds out to the narrowest of its fixed ranges (e.g. 25-34 becomes 25-49, 18-65 becomes 18+)."},"ageMax":{"type":"integer","minimum":13,"maximum":100,"description":"Maximum age. Same per-platform application and clamping as ageMin."},"gender":{"type":"string","enum":["all","male","female"],"description":"Restrict by gender. 'all' (default) targets everyone. Applied on Meta, TikTok, Pinterest, LinkedIn, X, Reddit and Google Search/Display (Google excludes the other gender); rejected with 400 on OpenAI and on Google Performance Max / Demand Gen."},"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\nexpress all four. Google maps only `top_10` (its INCOME_RANGE_90_UP); other\ntiers on Google, and any income tier on LinkedIn / X / Pinterest, are rejected.\nOn Meta, income/zip targeting requires the relevant `specialAdCategories` to be\nunset (housing/employment/credit ads cannot use it).\n"},"languages":{"type":"array","items":{"type":"string"},"description":"Language codes restricting the audience by language. Applied on Meta, Google, TikTok, LinkedIn, X, Pinterest and Reddit; rejected with 400 on OpenAI. A code the platform cannot target returns 400 listing the ones it can.\n\nOn Meta: ISO 639-1 codes (e.g. ['en']). A bare code targets all regional variants (\"en\" = all English); use a region-qualified code (\"en_GB\", \"pt_BR\") for a specific one. Meta numeric locale ids (e.g. \"24\" for English UK) are also accepted. Unknown values are rejected.\n\nPOST /v1/ads/create and POST /v1/ads/boost take the same format."},"interests":{"type":"array","description":"Interest entities from /v1/ads/targeting/search?dimension=interest. Each carries the platform's opaque id.\n\n- Google: applied as ad-group interest criteria (affinity and in-market categories) on Display and Search ad groups the request creates. Interests are create-only.\n- Google rejections (400): on Performance Max, on Demand Gen (use the Demand Gen audience `userInterests` there), and when attaching to an existing ad group (`adSetId`).\n- OpenAI: rejected with 400.\n- TikTok: bare numeric ids are interest categories (`interest_category_ids`); ids like `keyword:123456` from `dimension=interestKeyword` are additional interests (`interest_keyword_ids`). Any other id returns 422 naming `targeting.interests`.\n- TikTok matching: people who fit ANY selected interest, additional interest or behavior (one OR'd group). That group is ANDed with location, age, gender and the other dimensions.\n","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 (Meta, TikTok and LinkedIn).\n\n**On TikTok** they target people who, in the picked categories:\n\n- interacted with videos (watched to the end, liked, commented or shared, last 15 days);\n- interacted with creators (followed or viewed the profile);\n- or viewed videos with a picked hashtag (`hashtag:<id>` ids from `dimension=hashtag`, sent as a `HASHTAG_RELATED` action with `VIEW_HASHTAG`).\n\nThe ad group then uses the TikTok placement only. Behaviors are OR'd with interests and additional interests.\n","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"workPositions":{"type":"array","description":"Meta only. Job title entities from /v1/ads/targeting/search?dimension=workPosition. Not interchangeable with the LinkedIn `jobTitles` URN fragments.","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"workEmployers":{"type":"array","description":"Meta only. Employer entities from /v1/ads/targeting/search?dimension=workEmployer.","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"workIndustries":{"type":"array","description":"Meta only. Work-industry entities from /v1/ads/targeting/search?dimension=workIndustry. Not interchangeable with the LinkedIn `industries` URN fragments.","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, or the full urn:li:industry:* URN from /v1/ads/targeting/search?dimension=industry."},"companySizes":{"type":"array","items":{"type":"string"},"description":"LinkedIn B2B only. Single-letter size codes (A to I), or the full urn:li:staffCountRange:* URN from /v1/ads/targeting/search?dimension=companySize."},"seniorities":{"type":"array","items":{"type":"string"},"description":"LinkedIn B2B only. Seniority URN id fragments, or the full urn:li:seniority:* URN from /v1/ads/targeting/search?dimension=seniority."},"jobFunctions":{"type":"array","items":{"type":"string"},"description":"LinkedIn B2B only. Function URN id fragments, or the full urn:li:function:* URN from /v1/ads/targeting/search?dimension=jobFunction."},"skills":{"type":"array","items":{"type":"string"},"description":"LinkedIn B2B only. Member skills (e.g. Python, Recruiting): skill URN id fragments, or the full urn:li:skill:* URN from /v1/ads/targeting/search?dimension=skill. Values are ORed; the facet is ANDed with the other facets. On an ad set update an empty list removes the skills."},"audienceInclude":{"type":"array","items":{"type":"string"},"description":"Platform audience IDs to include, as returned by GET /v1/ads/audiences:\n\n- Meta: custom audience ids.\n- TikTok: audience ids.\n- Pinterest: customer list ids.\n- LinkedIn: segment ids (the platformAudienceId from GET /v1/ads/audiences). Zernio resolves it to the targetable LinkedIn ad segment; an unknown id returns 400.\n- Google: user list ids.\n- X: custom audience ids.\n- Reddit: ids of custom audiences built in Reddit Ads Manager (GET /v1/ads/audiences does not list Reddit audiences).\n- OpenAI: not supported (400)."},"audienceExclude":{"type":"array","items":{"type":"string"},"description":"Platform audience IDs to exclude; same ID formats as audienceInclude. Not supported on OpenAI (400)."},"communities":{"type":"array","items":{"type":"string","minLength":1},"description":"Reddit only (400 elsewhere). Subreddits to target, by name, with or without the `r/` prefix (e.g. `['marketing', 'r/startups']`), as returned by /v1/ads/targeting/search?dimension=community."},"excludedCommunities":{"type":"array","items":{"type":"string","minLength":1},"description":"Reddit only (400 elsewhere). Subreddits to exclude, named like `communities`."},"conversationKeywords":{"type":"array","items":{"type":"string","minLength":1},"description":"Reddit only (400 elsewhere). Keywords that place the ad in Reddit conversations about them, as returned by /v1/ads/targeting/search?dimension=conversationKeyword."},"excludedConversationKeywords":{"type":"array","items":{"type":"string","minLength":1},"description":"Reddit only (400 elsewhere). Conversation keywords to keep the ad away from."}}},"MetaPlacementAssets":{"type":"object","description":"Meta placement asset customization: pin a SPECIFIC asset (image OR video) to each placement group on a SINGLE ad (e.g. a 4:5 image on Feed and a 9:16 image on Stories/Reels). This is what Meta Ads Manager produces with \"different creative per placement\".\n\nMapped to the creative's `asset_feed_spec` (`optimization_type: PLACEMENT`) + `asset_customization_rules`.\n\n- Each rule can pin one `headline`, `body` and `description`; omitted fields and unmatched placements use the request's top-level copy.\n- Each rule's `placements` accepts the same fields as the top-level `placements` object. Meta enforces co-selection rules and returns an actionable error.\n\nA block is all-image OR all-video, never mixed (Meta's asset_feed_spec carries one ad format). Exactly one catch-all default is required.\n\n- Image mode: `defaultImageUrl` + `rules[].imageUrl`.\n- Video mode: `defaultVideoUrl` or `defaultVideoId` + `rules[].videoUrl` or `rules[].videoId`, with optional `thumbnailUrl`/`defaultThumbnailUrl` posters (Meta auto-generates them when omitted). An id reuses a video already on the ad account and wins over a URL in the same slot; the two can mix across slots.\n\nMeta controls text rendering by placement and format. Validation accepts these fields but does not prove every field appears in delivery. Preview the ad, and put copy that must always be visible into the image or video itself.\n","example":{"defaultImageUrl":"https://example.com/feed-4x5.jpg","rules":[{"imageUrl":"https://example.com/feed-4x5.jpg","headline":"Build with Zernio","body":"Schedule social posts from your app.","description":"One API for your social content.","placements":{"publisherPlatforms":["facebook"],"facebookPositions":["feed"]}},{"imageUrl":"https://example.com/story-9x16.jpg","headline":"Your next story","body":"Bring your social workflow to Zernio.","placements":{"publisherPlatforms":["facebook"],"facebookPositions":["story","facebook_reels"]}}]},"required":["rules"],"properties":{"defaultImageUrl":{"type":"string","format":"uri","description":"Image mode. Catch-all image for any placement no rule matches. Required in image mode (Meta mandates a default rule)."},"defaultVideoUrl":{"type":"string","format":"uri","description":"Video mode. Catch-all video for any placement no rule matches. Video mode requires this or `defaultVideoId`."},"defaultVideoId":{"type":"string","minLength":1,"description":"Video mode. ID of a video already on the ad account, used as the catch-all instead of uploading `defaultVideoUrl`. Wins over `defaultVideoUrl`. A video still processing after 30 seconds returns 409."},"defaultThumbnailUrl":{"type":"string","format":"uri","description":"Video mode (optional). Poster image for the default video; Meta auto-generates one when omitted."},"rules":{"type":"array","minItems":1,"maxItems":10,"description":"One entry per placement group you want to pin a specific asset to.","items":{"type":"object","required":["placements"],"properties":{"imageUrl":{"type":"string","format":"uri","description":"Image mode. The image to deliver for this rule's placements."},"videoUrl":{"type":"string","format":"uri","description":"Video mode. The video to deliver for this rule's placements. Each rule needs this or `videoId`."},"videoId":{"type":"string","minLength":1,"description":"Video mode. ID of a video already on the ad account, used for this rule instead of uploading `videoUrl`. Wins over `videoUrl`. A video still processing after 30 seconds returns 409."},"thumbnailUrl":{"type":"string","format":"uri","description":"Video mode (optional). Poster image for this rule's video; auto-generated when omitted."},"headline":{"type":"string","minLength":1,"maxLength":255,"description":"One headline pinned to this rule. Omit to inherit the top-level headline."},"body":{"type":"string","minLength":1,"description":"One primary text pinned to this rule. Omit to inherit the top-level body."},"description":{"type":"string","minLength":1,"maxLength":255,"description":"One link description pinned to this rule. Omit to inherit the top-level description."},"placements":{"type":"object","description":"Placements this asset is pinned to. At least one field must be set (an empty rule is invalid; that role is served by the default asset). Same enums as the top-level `placements` object.","properties":{"publisherPlatforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","threads","messenger","audience_network","whatsapp"]}},"facebookPositions":{"type":"array","items":{"type":"string","enum":["feed","right_hand_column","marketplace","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"]}}}}}}}}},"MetaCreativeFeatures":{"type":"object","additionalProperties":{"type":"string","enum":["OPT_IN","OPT_OUT"]},"propertyNames":{"pattern":"^[a-z0-9_]+$"},"description":"Meta Advantage+ creative enhancements. Map snake_case feature names to OPT_IN or OPT_OUT; Meta validates supported keys and unspecified features default to OPT_OUT. auto_promotion_tag is an Advantage+ enhancement, not the Ads Manager Promotion setting. The deprecated standard_enhancements bundle (subcode 3858504) is a 400 before any Meta call.","example":{"auto_promotion_tag":"OPT_IN"}},"MetaPromotion":{"type":["object","null"],"description":"Not supported. Send null or omit the field, and set the Promotion on the ad in Ads Manager. Any object is rejected with 400 invalid_field_value.\n\nMeta validates creative_sourcing_spec.promotion_metadata_spec on the create call and then discards it, so a Promotion set through the Marketing API never reaches the creative. Verified on 2026-09-11 across Graph v19.0 to v25.0 and every write path.\n","example":null},"GoogleSitelink":{"type":"object","required":["text","linkUrl"],"properties":{"text":{"type":"string","minLength":1,"maxLength":25},"linkUrl":{"type":"string","format":"uri"},"description1":{"type":"string","minLength":1,"maxLength":35},"description2":{"type":"string","minLength":1,"maxLength":35}}},"GoogleStructuredSnippet":{"type":"object","required":["header","values"],"properties":{"header":{"type":"string","enum":["Amenities","Brands","Courses","Degree programs","Destinations","Featured hotels","Insurance coverage","Models","Neighborhoods","Service catalog","Shows","Styles","Types"]},"values":{"type":"array","minItems":3,"maxItems":10,"items":{"type":"string","minLength":1,"maxLength":25}}}},"GoogleAssetUpdate":{"type":"object","required":["assetResourceName"],"properties":{"assetResourceName":{"type":"string","pattern":"^customers/\\d+/assets/\\d+$","description":"Asset resource name returned by a list operation. Must belong to the selected customer."},"sitelinkAsset":{"type":"object","properties":{"linkText":{"type":"string","minLength":1,"maxLength":25},"description1":{"type":"string","maxLength":35},"description2":{"type":"string","maxLength":35},"linkUrl":{"type":"string","format":"uri","description":"Alias for finalUrls with one URL. Do not supply both."}},"minProperties":1},"finalUrls":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1},"calloutAsset":{"type":"object","required":["calloutText"],"properties":{"calloutText":{"type":"string","minLength":1,"maxLength":25}}},"structuredSnippetAsset":{"$ref":"#/components/schemas/GoogleStructuredSnippet"}},"description":"Supply fields for exactly one asset type per update. finalUrls may accompany sitelinkAsset. Shared asset edits affect every attachment using the asset."},"GoogleLocationTargetingType":{"type":"string","enum":["presence","presence_or_interest"],"description":"Google only. Who a campaign's location targeting reaches (Google's `campaign.geo_target_type_setting.positive_geo_target_type`).\n\n- `presence`: people in, or regularly in, the targeted locations.\n- `presence_or_interest`: also people searching for or showing interest in them. Google's default when omitted.\n\nAccepted on Search, Display and Performance Max campaigns. Excluded locations always use presence (Google refuses presence_or_interest for exclusions on these campaign types).\n","example":"presence"},"GoogleDemandGenInput":{"type":"object","additionalProperties":false,"description":"Creative, channel and audience settings for a Google Demand Gen campaign (campaignType demand_gen). Creates one ad group with one ad: a multi-asset image ad, a video responsive ad when youtubeVideoIds is sent, or a carousel ad when carouselCards is sent.","required":["finalUrl","businessName","headlines","descriptions","images"],"properties":{"adGroupName":{"type":"string","maxLength":255,"description":"Defaults to the ad name."},"finalUrl":{"type":"string","format":"uri"},"businessName":{"type":"string","maxLength":25},"headlines":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string","maxLength":40},"description":"Distinct texts. A carousel ad takes exactly one."},"longHeadlines":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string","maxLength":90},"description":"Video ads only, and required there."},"descriptions":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string","maxLength":90},"description":"A carousel ad takes exactly one."},"callToAction":{"type":"string","maxLength":25,"description":"Image and carousel ads only. Call to action text such as 'Learn more'; Google picks one when omitted."},"images":{"type":"object","additionalProperties":false,"required":["logo"],"description":"Public image URLs. An image ad needs landscape or square; video and carousel ads take only one logo (carousel images go on each card).","properties":{"landscape":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","format":"uri"},"description":"1.91:1, at least 600x314."},"square":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","format":"uri"},"description":"1:1, at least 300x300."},"portrait":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","format":"uri"},"description":"4:5, at least 480x600."},"logo":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string","format":"uri"},"description":"1:1, at least 128x128."}}},"youtubeVideoIds":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string","pattern":"^[A-Za-z0-9_-]{11}$"},"description":"Makes the ad a video responsive ad."},"carouselCards":{"type":"array","minItems":2,"maxItems":10,"description":"Makes the ad a carousel ad. Each card needs its own image (no two cards may share one); use the same image shape on every card.\n\nCard images are uploaded to the account's asset library before the campaign is created, validateOnly included. Google checks cards against existing images; identical images are reused, not duplicated.\n","items":{"type":"object","additionalProperties":false,"required":["headline","images"],"properties":{"headline":{"type":"string","maxLength":40},"finalUrl":{"type":"string","format":"uri","description":"Defaults to demandGen.finalUrl."},"callToAction":{"type":"string","maxLength":25},"images":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"landscape":{"type":"string","format":"uri","description":"1.91:1."},"square":{"type":"string","format":"uri","description":"1:1."},"portrait":{"type":"string","format":"uri","description":"4:5."}}}}}},"channels":{"type":"array","minItems":1,"items":{"type":"string","enum":["youtube_in_stream","youtube_in_feed","youtube_shorts","discover","gmail","display"]},"description":"Channel controls on the new ad group. Only the listed channels serve; Google Maps, which this list cannot select, is turned off. Omit to send no channel controls, so Google applies its default for a new ad group: all Demand Gen channels, Google Maps included."},"audience":{"$ref":"#/components/schemas/GoogleDemandGenAudience"},"audienceId":{"type":"string","description":"Attach an existing Google Audience by numeric id instead of audience."}}},"GoogleDemandGenAudience":{"type":"object","additionalProperties":false,"minProperties":1,"description":"Created as a Google Audience and attached to the ad group. Send at least one dimension. Ids are numeric Google ids (user lists, interest categories, custom audiences) from the same customer.","properties":{"userLists":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string"}},"userInterests":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string"}},"customAudiences":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string"}},"ageRanges":{"type":"array","minItems":1,"maxItems":6,"items":{"type":"object","required":["min"],"properties":{"min":{"type":"integer","enum":[18,25,35,45,55,65]},"max":{"type":"integer","enum":[24,34,44,54,64],"description":"Omit for no upper bound."}}}},"genders":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"string","enum":["male","female","undetermined"]}}}},"GoogleDemandGenUpdate":{"type":"object","additionalProperties":false,"minProperties":1,"description":"Partial edit of a Google Demand Gen ad, sent in one atomic Google request. Every field you send replaces that whole field; fields you omit are kept.\n\nWhich creative fields apply depends on the ad (read from Google). A field the ad does not take returns 422.\n\n- Image ads: headlines, descriptions, businessName, callToAction and images (landscape, square, portrait, logo).\n- Video ads: headlines, longHeadlines, descriptions, businessName, youtubeVideoIds and exactly one images.logo.\n- Carousel ads: exactly one headline, one description, one logo, businessName and callToAction. Their cards cannot be edited: create a new carousel ad.\n\nNew images are uploaded as new Google assets; the previous ones stay in the account's asset library.\n\n**Ad group fields.** `channels`, `audience` and `audienceId` change the ad's ad group, so they apply to every ad in it. `audience` builds a new Google Audience and attaches it in place of the current one (the previous one is detached, not deleted); `audienceId` attaches an existing one.\n\nAd groups of campaigns migrated from Discovery use ungrouped audience segments, and Google refuses an Audience on them.\n","properties":{"finalUrl":{"type":"string","format":"uri"},"businessName":{"type":"string","maxLength":25},"headlines":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string","maxLength":40}},"longHeadlines":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string","maxLength":90},"description":"Video ads only."},"descriptions":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string","maxLength":90}},"callToAction":{"type":"string","maxLength":25,"description":"Image and carousel ads only."},"images":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"landscape":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","format":"uri"}},"square":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","format":"uri"}},"portrait":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","format":"uri"}},"logo":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string","format":"uri"}}}},"youtubeVideoIds":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string","pattern":"^[A-Za-z0-9_-]{11}$"},"description":"Video ads only."},"channels":{"type":"array","minItems":1,"items":{"type":"string","enum":["youtube_in_stream","youtube_in_feed","youtube_shorts","discover","gmail","display"]},"description":"Replaces the ad group's channel controls. Only the listed channels serve; Google Maps, which this list cannot select, is turned off. Omit to leave the ad group's channel controls unchanged."},"audience":{"$ref":"#/components/schemas/GoogleDemandGenAudience"},"audienceId":{"type":"string","description":"Attach an existing Google Audience by numeric id instead of audience."}}},"GooglePmaxAssetGroupInput":{"type":"object","additionalProperties":false,"required":["finalUrl","headlines","longHeadline","descriptions","businessName","images"],"description":"Google Performance Max creative assets. At least one description must be 60 characters or fewer. Texts within each list must be distinct.","properties":{"name":{"type":"string","minLength":1,"maxLength":128,"description":"Defaults to the request name."},"finalUrl":{"type":"string","format":"uri","pattern":"^https?://","description":"Required destination URL."},"headlines":{"type":"array","minItems":3,"maxItems":15,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":30}},"longHeadline":{"type":"string","minLength":1,"maxLength":90},"descriptions":{"type":"array","minItems":2,"maxItems":5,"uniqueItems":true,"description":"At least one description must be 60 characters or fewer.","items":{"type":"string","minLength":1,"maxLength":90}},"businessName":{"type":"string","minLength":1,"maxLength":25},"images":{"type":"object","additionalProperties":false,"required":["landscape","square","logo"],"description":"Public HTTP(S) image URLs. GIF, JPEG or PNG, at most 5120 KB per image. Google validates dimensions and aspect ratios.","properties":{"landscape":{"type":"array","minItems":1,"maxItems":20,"description":"Landscape marketing images. Aspect ratio 1.91:1, minimum 600 x 314 pixels.","items":{"type":"string","format":"uri","pattern":"^https?://"}},"square":{"type":"array","minItems":1,"maxItems":20,"description":"Square marketing images. Aspect ratio 1:1, minimum 300 x 300 pixels.","items":{"type":"string","format":"uri","pattern":"^https?://"}},"logo":{"type":"array","minItems":1,"maxItems":5,"description":"Required square logos. Aspect ratio 1:1, minimum 128 x 128 pixels.","items":{"type":"string","format":"uri","pattern":"^https?://"}}}},"youtubeVideoId":{"type":"string","pattern":"^[A-Za-z0-9_-]{11}$","description":"Optional existing YouTube video id. Google can generate video when omitted. Video uploads and arbitrary video URLs are not supported."}},"example":{"finalUrl":"https://zernio.com","headlines":["Schedule posts","One social API","Build with Zernio"],"longHeadline":"Schedule social content from your app with Zernio","descriptions":["Connect your social accounts.","Publish and manage social content through one API."],"businessName":"Zernio","images":{"landscape":["https://example.com/landscape.png"],"square":["https://example.com/square.png"],"logo":["https://example.com/logo.png"]}}},"GooglePmaxAssetGroupUpdate":{"type":"object","additionalProperties":false,"minProperties":1,"description":"Replacement assets for an existing Performance Max asset group, sent on PUT /v1/ads/{adId}. Send one field or many; a field you omit is left untouched.\n\nGoogle assets are immutable (AssetService only creates), so each field you send becomes new assets linked to the asset group, and the assets that role held are unlinked in the same atomic request. Re-sending a value the asset group already carries is a no-op for that asset, not a re-upload.\n\nUnlinked assets stay in the account's asset library: Google has no asset delete.\n\nAt least one description must be 60 characters or fewer. Texts within each list must be distinct.\n","properties":{"finalUrl":{"type":"string","format":"uri","pattern":"^https?://","description":"Replaces the asset group's final URL."},"headlines":{"type":"array","minItems":3,"maxItems":15,"uniqueItems":true,"description":"Replaces every HEADLINE asset on the group.","items":{"type":"string","minLength":1,"maxLength":30}},"longHeadline":{"type":"string","minLength":1,"maxLength":90,"description":"Replaces the LONG_HEADLINE asset."},"descriptions":{"type":"array","minItems":2,"maxItems":5,"uniqueItems":true,"description":"Replaces every DESCRIPTION asset. At least one must be 60 characters or fewer.","items":{"type":"string","minLength":1,"maxLength":90}},"businessName":{"type":"string","minLength":1,"maxLength":25,"description":"Replaces the BUSINESS_NAME asset."},"images":{"type":"object","additionalProperties":false,"minProperties":1,"description":"Public HTTP(S) image URLs. Each role you send replaces that role's images; roles you omit stay. GIF, JPEG or PNG, at most 5120 KB per image.","properties":{"landscape":{"type":"array","minItems":1,"maxItems":20,"description":"Replaces MARKETING_IMAGE assets. Aspect ratio 1.91:1, minimum 600 x 314 pixels.","items":{"type":"string","format":"uri","pattern":"^https?://"}},"square":{"type":"array","minItems":1,"maxItems":20,"description":"Replaces SQUARE_MARKETING_IMAGE assets. Aspect ratio 1:1, minimum 300 x 300 pixels.","items":{"type":"string","format":"uri","pattern":"^https?://"}},"logo":{"type":"array","minItems":1,"maxItems":5,"description":"Replaces LOGO assets. Aspect ratio 1:1, minimum 128 x 128 pixels.","items":{"type":"string","format":"uri","pattern":"^https?://"}}}},"youtubeVideoIds":{"type":"array","minItems":1,"maxItems":5,"description":"Replaces YOUTUBE_VIDEO assets with existing YouTube video ids. Video uploads and arbitrary video URLs are not supported.","items":{"type":"string","pattern":"^[A-Za-z0-9_-]{11}$"}}},"example":{"headlines":["Schedule posts","One social API","Build with Zernio"],"images":{"landscape":["https://example.com/new-landscape.png"]}}},"GooglePmaxAssetGroup":{"type":"object","required":["id","resourceName","campaignId","name","status","finalUrls","finalMobileUrls","path1","path2","adStrength","primaryStatus","primaryStatusReasons","assets"],"properties":{"id":{"type":"string","description":"Stable Google asset group id. Use it in the asset-group endpoints below."},"resourceName":{"type":"string","description":"customers/{customerId}/assetGroups/{assetGroupId}"},"campaignId":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","description":"Asset-group status on Google. Campaign status independently controls delivery."},"finalUrls":{"type":"array","items":{"type":"string","format":"uri"}},"finalMobileUrls":{"type":"array","items":{"type":"string","format":"uri"}},"path1":{"type":["string","null"]},"path2":{"type":["string","null"]},"adStrength":{"type":["string","null"],"description":"Google ad strength, such as POOR, AVERAGE, GOOD or EXCELLENT."},"primaryStatus":{"type":["string","null"],"description":"Why the group is or is not serving, such as ELIGIBLE, PAUSED or NOT_ELIGIBLE."},"primaryStatusReasons":{"type":"array","items":{"type":"string"}},"assets":{"type":"array","items":{"type":"object","required":["resourceName","fieldType","status"],"properties":{"resourceName":{"type":"string"},"fieldType":{"type":"string","description":"Google asset role, such as HEADLINE or LOGO."},"status":{"type":"string"},"text":{"type":"string"},"imageUrl":{"type":"string","format":"uri"},"youtubeVideoId":{"type":"string"}}}}}},"GooglePmaxAssetGroupDetail":{"allOf":[{"$ref":"#/components/schemas/GooglePmaxAssetGroup"},{"type":"object","required":["listingGroupFilters"],"properties":{"listingGroupFilters":{"type":"array","description":"The asset group's listing-group tree as flat nodes (retail campaigns). Empty when the group has none.","items":{"$ref":"#/components/schemas/GoogleListingGroupFilterNode"}}}}]},"GoogleListingGroupFilterNode":{"type":"object","required":["id","resourceName","parentResourceName","type","listingSource","dimension"],"properties":{"id":{"type":"string"},"resourceName":{"type":"string","description":"customers/{customerId}/assetGroupListingGroupFilters/{assetGroupId}~{filterId}"},"parentResourceName":{"type":["string","null"],"description":"Null for the root node."},"type":{"type":"string","enum":["SUBDIVISION","UNIT_INCLUDED","UNIT_EXCLUDED"]},"listingSource":{"type":"string"},"dimension":{"type":["object","null"],"description":"Google's case value for the node, such as { productBrand: { value: 'Acme' } }. A dimension with no value is the everything-else node. Null for the root."}}},"GoogleAssetGroupAssetLink":{"type":"object","required":["fieldType"],"description":"Link one asset to the asset group. Send exactly one of asset (an existing asset), text, imageUrl or youtubeVideoId (new content, created in the same request).","properties":{"fieldType":{"type":"string","description":"Google AssetFieldType, such as HEADLINE, LONG_HEADLINE, DESCRIPTION, BUSINESS_NAME, MARKETING_IMAGE, SQUARE_MARKETING_IMAGE, PORTRAIT_MARKETING_IMAGE, LOGO, LANDSCAPE_LOGO or YOUTUBE_VIDEO."},"asset":{"type":"string","description":"Existing asset id or resource name customers/{customerId}/assets/{assetId}. Must belong to the campaign's ad account."},"text":{"type":"string","maxLength":90,"description":"Text assets link as HEADLINE, LONG_HEADLINE, DESCRIPTION or BUSINESS_NAME."},"imageUrl":{"type":"string","format":"uri","description":"Public http(s) image. Links as an image role or LOGO / LANDSCAPE_LOGO."},"youtubeVideoId":{"type":"string","pattern":"^[A-Za-z0-9_-]{11}$","description":"Links as YOUTUBE_VIDEO."}}},"GoogleAssetGroupAssetUnlink":{"type":"object","required":["fieldType","asset"],"properties":{"fieldType":{"type":"string"},"asset":{"type":"string","description":"Asset id or resource name, as returned in the asset group's assets."}}},"GoogleListingGroupDimension":{"type":"object","description":"Exactly one key. Omit the value (for example { productBrand: {} }) for the everything-else node of that level.","properties":{"productBrand":{"type":"object","properties":{"value":{"type":"string"}}},"productCategory":{"type":"object","required":["level"],"properties":{"categoryId":{"type":"string","description":"Google product category id."},"level":{"type":"string","enum":["LEVEL1","LEVEL2","LEVEL3","LEVEL4","LEVEL5"]}}},"productType":{"type":"object","required":["level"],"properties":{"value":{"type":"string"},"level":{"type":"string","enum":["LEVEL1","LEVEL2","LEVEL3","LEVEL4","LEVEL5"]}}},"productItemId":{"type":"object","properties":{"value":{"type":"string"}}},"productCondition":{"type":"object","properties":{"condition":{"type":"string","enum":["NEW","REFURBISHED","USED"]}}},"productChannel":{"type":"object","properties":{"channel":{"type":"string","enum":["ONLINE","LOCAL"]}}},"productCustomAttribute":{"type":"object","required":["index"],"properties":{"value":{"type":"string"},"index":{"type":"string","enum":["INDEX0","INDEX1","INDEX2","INDEX3","INDEX4"]}}}}},"GoogleListingGroupNode":{"type":"object","required":["dimension"],"properties":{"dimension":{"$ref":"#/components/schemas/GoogleListingGroupDimension"},"excluded":{"type":"boolean","description":"Leaf only. true excludes these products."},"children":{"type":"array","minItems":2,"description":"Makes the node a subdivision. Children share one dimension (and level or index) and include exactly one everything-else node.","items":{"$ref":"#/components/schemas/GoogleListingGroupNode"}}}},"GoogleListingGroupTree":{"type":"object","description":"The root of a Performance Max retail listing-group tree (listing source SHOPPING). No children targets all products. Requires a campaign linked to Merchant Center.","properties":{"children":{"type":"array","minItems":2,"items":{"$ref":"#/components/schemas/GoogleListingGroupNode"}}},"example":{"children":[{"dimension":{"productBrand":{"value":"Acme"}}},{"dimension":{"productBrand":{}},"excluded":true}]}},"GoogleRecommendationMetrics":{"type":"object","properties":{"impressions":{"type":"number"},"clicks":{"type":"number"},"cost":{"type":"number","description":"Account currency units."},"conversions":{"type":"number"},"conversionsValue":{"type":"number"},"videoViews":{"type":"number"}}},"GoogleRecommendation":{"type":"object","required":["resourceName","id","type","dismissed","campaignId","campaignIds","adGroupId","campaignBudgetId","impact","details"],"properties":{"resourceName":{"type":"string","description":"customers/{customerId}/recommendations/{id}. Pass it to apply or dismiss."},"id":{"type":"string"},"type":{"type":"string","description":"Google RecommendationType, such as CAMPAIGN_BUDGET, KEYWORD or SET_TARGET_CPA."},"dismissed":{"type":"boolean"},"campaignId":{"type":["string","null"]},"campaignIds":{"type":"array","items":{"type":"string"},"description":"Every campaign the recommendation targets (several for account-level types)."},"adGroupId":{"type":["string","null"]},"campaignBudgetId":{"type":["string","null"]},"impact":{"type":["object","null"],"description":"Google's estimate over its own window. Null when Google gives none for the type.","properties":{"base":{"$ref":"#/components/schemas/GoogleRecommendationMetrics"},"potential":{"$ref":"#/components/schemas/GoogleRecommendationMetrics"}}},"details":{"type":["object","null"],"description":"The type-specific recommendation payload exactly as Google returns it (camelCase, amounts in micros), for example recommendedTargetCpaMicros or budgetOptions."}},"example":{"resourceName":"customers/9122445560/recommendations/NjgzMzAxODc4NS0yNDItMTc5MDQzODQxMDc1NC0rMjQxOTE1ODU2NzEtMA","id":"NjgzMzAxODc4NS0yNDItMTc5MDQzODQxMDc1NC0rMjQxOTE1ODU2NzEtMA","type":"FORECASTING_SET_TARGET_CPA","dismissed":false,"campaignId":"24191585671","campaignIds":["24191585671"],"adGroupId":null,"campaignBudgetId":null,"impact":{"base":{"impressions":2790,"clicks":87,"cost":420,"conversions":3.96,"conversionsValue":0,"videoViews":0},"potential":{"impressions":5909,"clicks":185,"cost":889.58,"conversions":8.39,"conversionsValue":0,"videoViews":0}},"details":{"recommendedTargetCpaMicros":"105420000","campaignBudget":{"currentAmountMicros":"60000000","recommendedNewAmountMicros":"140000000","newStartDate":"2026-10-01"}}}},"GoogleRecommendationResult":{"type":"object","required":["resourceName","status"],"properties":{"resourceName":{"type":"string"},"status":{"type":"string","enum":["applied","dismissed","failed"]},"error":{"type":"string","description":"Google's message when status is failed."}}},"GoogleRsaHeadline":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":30},"pinnedField":{"type":"string","enum":["HEADLINE_1","HEADLINE_2","HEADLINE_3"],"description":"Optional fixed headline position. Omit to leave the asset unpinned."}}},"GoogleRsaDescription":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":90},"pinnedField":{"type":"string","enum":["DESCRIPTION_1","DESCRIPTION_2"],"description":"Optional fixed description position. Omit to leave the asset unpinned."}}},"MetaRecoveredWrites":{"type":"array","description":"Meta only, present only when needed. Every object this request did not get confirmed by its first POST: found by name after Meta lost or failed its answer (`adopted`), or created by a second POST after a Meta 5xx (`repostedAfter`).\n\nA re-POSTed object may have a twin from the first POST that Meta wrote late: check its parent for a duplicate name. Send `retryOnServerError: false` to never re-POST.\n","items":{"type":"object","required":["type","id"],"properties":{"type":{"type":"string","enum":["campaign","adset","ad"]},"id":{"type":"string","description":"The Meta object id this response uses."},"adopted":{"type":"boolean","description":"Always true when present. Zernio found this object by name under its parent and reused it instead of creating it again."},"repostedAfter":{"type":"string","enum":["server_error"],"description":"Zernio sent the create again after Meta answered a 5xx and the read-back found no such object."}}}},"InstagramVideoFallback":{"type":"object","description":"Meta only. Present when Meta refused an existing Instagram video as the boosted ad (code 100, subcode 1815279: upload it to Facebook first) and Zernio created the ad another way:\n\n- `instagram_video_reuploaded`: the video was copied into the ad account, and the ad still references the original post.\n- `instagram_video_rehosted_copy`: the video was uploaded as a new Facebook video in a new Page post, so the ad does not show the original post's likes and comments.\n\nSend `rehostOnInstagramVideoRejection: false` on the boost to get Meta's error instead.\n","required":["kind","linkedToOriginalPost","videoId","platformError"],"properties":{"kind":{"type":"string","enum":["instagram_video_reuploaded","instagram_video_rehosted_copy"]},"linkedToOriginalPost":{"type":"boolean","description":"True when the ad still references the original Instagram post and keeps its engagement."},"videoId":{"type":"string","description":"The Facebook-side ad video Zernio made.\n\n- instagram_video_reuploaded: the copy in the ad account video library (possibly one made by an earlier boost of the same media, reused). The creative carries it as video_id, unless Meta accepted the plain post reference once the copy existed; then the copy is kept for that reference.\n- instagram_video_rehosted_copy: the new upload the creative uses (an unused copy made by this request is deleted)."},"platformError":{"type":"object","description":"Meta's original refusal.","required":["message"],"properties":{"code":{"type":"integer","example":100},"subcode":{"type":"integer","example":1815279},"message":{"type":"string"},"fbtraceId":{"type":"string"}}}}},"Ad":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"platform":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit","microsoft"]},"profileId":{"type":"string","description":"Profile the row belongs to: the profile of its owning connection (`accountId`); when that connection no longer exists, the requested profile (`profileId` filter) that reaches the row ad account, else the profile of the oldest connection of the row owner that reaches it."},"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 switch as configured on the platform, independent of its parents. An ACTIVE ad under a paused ad set or campaign still reads ACTIVE here while `status` reads `paused`.\n\n**Sources:**\n\n- Meta: `configured_status`.\n- TikTok: ad `operation_status` (ENABLE -> ACTIVE, DISABLE -> PAUSED).\n- ChatGPT (OpenAI): ad `status` (ACTIVE / PAUSED, plus ARCHIVED on OpenAI).\n- Reddit: `configured_status` (ACTIVE / PAUSED / ARCHIVED).\n\nOn create it is read back from the platform, not copied from the request. A `PAUSED` create pauses only the top-most object it creates, so an ad under a new paused campaign or ad set reads ACTIVE with `status: paused`; only an ad attached to an existing ad set reads PAUSED.\n\nDistinct from `status`, the ancestor-cascaded delivery status. Present only for Meta, TikTok, OpenAI and Reddit ads created or synced after the field was added for that platform; null otherwise.\n","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","page_likes","page_visits","job_applicants"],"description":"Available goals vary by platform:\n\n- **Meta (Facebook/Instagram):** all 11, including `lead_conversion` (website pixel lead optimization), `catalog_sales` (Advantage+ catalog ads), `page_likes` (Page Likes conversion location under Engagement) and `page_visits` (Page visits and followers under Traffic).\n- **TikTok:** engagement, traffic, awareness, video_views, lead_generation, conversions, app_promotion.\n- **LinkedIn:** all Meta goals except app_promotion / lead_conversion / catalog_sales / page_likes / page_visits.\n- **X:** engagement, traffic, awareness, video_views, app_promotion.\n- **Pinterest:** only engagement, traffic, awareness, video_views.\n- **Google Ads:** only engagement, traffic, awareness (video_views is rejected at create with 422 FEATURE_NOT_AVAILABLE)."},"isExternal":{"type":"boolean","description":"True for ads synced from platform ad managers"},"synced":{"type":"boolean","description":"Only on GET /v1/ads/{adId}. True when the ad comes from Zernio's synced store; false when it was read live from Meta because it is not synced yet (request made with `accountId`). An unsynced ad has no `id`."},"budget":{"type":["object","null"],"properties":{"amount":{"type":"number"},"type":{"type":"string","enum":["daily","lifetime"]},"daily":{"type":"number","description":"LinkedIn and X only. The daily budget (LinkedIn: the parent campaign's `dailyBudget`; X: the line item's, or the campaign's when the line item has none). Both allow a daily AND a lifetime budget together, which `amount`/`type` cannot express (daily wins there); read `daily` and `lifetime` to see both."},"lifetime":{"type":"number","description":"LinkedIn and X only. The lifetime total (LinkedIn: the parent campaign's `totalBudget`; X: `total_budget_amount_local_micro`, for example the `lifetimeBudgetCap` of a boost), readable even when a daily budget is also set."},"pacing":{"type":"string","description":"LinkedIn only. The campaign's `pacingStrategy`: how fast LinkedIn may spend the budget. Typically LINEAR or ACCELERATED; the list is open."}}},"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":"The platform's own campaign objective, verbatim, alongside the normalized `goal` it maps to.\nThe mapping is many-to-one, so `goal` alone cannot be mapped back to it.\n\n- Meta: campaign `objective` (e.g. OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_TRAFFIC).\n- LinkedIn: campaign `objectiveType` (e.g. WEBSITE_VISIT, LEAD_GENERATION, BRAND_AWARENESS,\n  VIDEO_VIEW, ENGAGEMENT, JOB_APPLICANT, WEBSITE_CONVERSION). The list is open, so treat an\n  unrecognized value as valid rather than an error.\n- TikTok and Pinterest: their raw objective_type.\n\nNull on platforms that report none, and on LinkedIn ads not yet re-synced.\n","example":"OUTCOME_SALES"},"optimizationGoal":{"type":["string","null"],"description":"What the delivery system optimizes for, at ad-set level. The value space depends on `platform`:\n\n- Meta: ad set `optimization_goal` (e.g. OFFSITE_CONVERSIONS, VALUE, LEAD_GENERATION, LINK_CLICKS).\n- LinkedIn: the campaign's EFFECTIVE `optimizationTargetType`, refreshed from LinkedIn on every sync rather than echoing the create input. `NONE` means manual bidding: a real value, not missing data.\n- LinkedIn auto-bid values: MAX_IMPRESSION / MAX_CLICK / MAX_CONVERSION / MAX_VIDEO_VIEW / MAX_LEAD / MAX_REACH.\n- LinkedIn target-cost values: TARGET_COST_PER_CLICK / TARGET_COST_PER_IMPRESSION / TARGET_COST_PER_VIDEO_VIEW. Cost-cap values: the CAP_COST_AND_MAXIMIZE_* family.\n","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. `null` for non-LinkedIn ads.\n\n- `CPM`: cost per thousand impressions. For campaign type SPONSORED_INMAILS, `CPM` bills as cost-per-send x 1000.\n- `CPC`: cost per click.\n- `CPV`: cost per video view.\n\nOn LinkedIn this is the axis that pairs with `bidAmount`; there is no `bidStrategy`.\n","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 says so.\n\n- `[]`: no serving data (a non-LinkedIn ad, or a LinkedIn ad not yet re-synced).\n- `[\"RUNNABLE\"]`: the campaign is eligible to serve.\n- Anything else is a hold. Known values: 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, STOPPED.\n\nThe list is open on purpose: treat unrecognized values as holds, not errors. End-date and total-budget holds are terminal and surface as `status: completed`; the rest surface as `status: paused`.\n\nA 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.\n","example":["ACCOUNT_TOTAL_BUDGET_HOLD"]},"platformAdAccountName":{"type":["string","null"],"description":"Human-readable advertiser/account name (Meta `AdAccount.name`, TikTok\n`advertiser_name`, LinkedIn / X / Pinterest equivalents). Refreshed every\nsync so platform-side renames propagate within one cycle. `null` when the\nplatform doesn't return a name or the sync hasn't run yet.\n","example":"Zernio - previously Late"},"platformCreatedAt":{"type":["string","null"],"format":"date-time","description":"Platform-reported creation timestamp (Meta `created_time`, TikTok `create_time`). Read this field to sort or filter by when the ad was actually created on the platform.\n\nDistinct from `createdAt`, which is when Zernio first synced the doc.\n\n`null` for legacy ads synced before this field was added; aggregations then fall back to `createdAt`.\n"},"bidStrategy":{"anyOf":[{"$ref":"#/components/schemas/BidStrategy"},{"type":"null"}],"description":"Ad-set bid strategy (overrides campaign level on Meta). Populated for Meta and\nTikTok. TikTok's native `bid_type` is normalized to the cross-platform Meta enum:\n`BID_TYPE_NO_BID` -> `LOWEST_COST_WITHOUT_CAP`, `BID_TYPE_CUSTOM` ->\n`LOWEST_COST_WITH_BID_CAP`, deep_bid_type=MIN_ROAS or roas_bid>0 ->\n`LOWEST_COST_WITH_MIN_ROAS`, `BID_TYPE_MAX_CONVERSION` -> `LOWEST_COST_WITHOUT_CAP`.\n","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).\n\n- Meta: `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`).\n- TikTok: 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.\n- LinkedIn: 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.\n- LinkedIn pairing: it pairs with `costType`, NOT with `bidStrategy`, which LinkedIn does not have. A value of `0` is a real, delivery-stopping configuration, not \"unset\", so do not gate this field on `bidStrategy` for LinkedIn ads.\n\nSource: facebook-business-sdk-codegen api_specs/specs/AdSet.json (`bid_amount`).\n","example":5},"roasAverageFloor":{"type":["number","null"],"description":"Minimum ROAS as a decimal multiplier (2.0 = 2.0x ROAS). Populated when bidStrategy\nis `LOWEST_COST_WITH_MIN_ROAS`.\n\n- Meta source: decoded from `bid_constraints.roas_average_floor` (Meta stores as\n  fixed-point int × 10000; we return the decimal).\n- TikTok source: `roas_bid` on the ad group (already a decimal).\n\nSource: facebook-business-sdk-codegen api_specs/specs/AdCampaignBidConstraint.json.\n","example":2},"specialAdCategories":{"type":"array","items":{"type":"string"},"description":"Special ad categories declared when Zernio created this ad (`specialAdCategories` on POST /v1/ads/create or /v1/ads/boost), e.g. [\"HOUSING\"]. Empty or absent when none was declared or the ad was created outside Zernio."},"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":{"assetGroup":{"$ref":"#/components/schemas/GooglePmaxAssetGroupInput","description":"Initial Performance Max asset group input. Use the asset-groups endpoint for current Google assets."},"assetGroupResourceName":{"type":"string","description":"Google resource name of the created Performance Max asset group.","example":"customers/9122445560/assetGroups/123456789"},"headlines":{"type":"array","maxItems":15,"items":{"oneOf":[{"type":"string"},{"$ref":"#/components/schemas/GoogleRsaHeadline"}]},"description":"Google RSA: the headline assets as objects (3 to 15). Meta: every title variation of the creative (`asset_feed_spec.titles`) as strings, the same shape as the `headlines` create input. Present only with 2 or more titles; a single title is `headline`."},"descriptions":{"type":"array","maxItems":4,"items":{"oneOf":[{"type":"string"},{"$ref":"#/components/schemas/GoogleRsaDescription"}]},"description":"Google RSA: the description assets as objects (2 to 4). Meta: every description variation of the creative (`asset_feed_spec.descriptions`) as strings, the same shape as the `descriptions` create input. Present only with 2 or more descriptions; a single one is `description`."},"headline":{"type":"string","description":"Meta: the creative's title (`link_data.name`, `video_data.title`, or the first `asset_feed_spec.titles` entry). Absent when the creative has none."},"bodies":{"type":"array","items":{"type":"string"},"description":"Meta: every primary text variation of the creative (`asset_feed_spec.bodies`), the same shape as the `bodies` create input. Present only with 2 or more texts; a single text is `body`."},"description":{"type":"string","description":"Meta: the creative's description under the title (`link_data.description`, `video_data.link_description`, or the first `asset_feed_spec.descriptions` entry)."},"callToAction":{"type":"string","description":"Meta: the call to action type (`call_to_action.type`, or the first `asset_feed_spec.call_to_action_types` entry), e.g. LEARN_MORE or SIGN_UP. TikTok: the ad's `call_to_action`.","example":"SIGN_UP"},"identityId":{"type":"string","description":"TikTok only, with `live=true` on GET /v1/ads/{adId}: the identity the ad runs as (`identity_id`), the same id GET /v1/ads/tiktok-identities lists."},"identityType":{"type":"string","description":"TikTok only, with `live=true`: the identity type (`identity_type`), e.g. TT_USER, BC_AUTH_TT, CUSTOMIZED_USER or AUTH_CODE."},"identityAuthorizedBcId":{"type":"string","description":"TikTok only, with `live=true`: the Business Center that authorized a BC_AUTH_TT identity (`identity_authorized_bc_id`)."},"tiktokItemId":{"type":"string","description":"TikTok only, with `live=true`: the TikTok post a Spark ad runs (`tiktok_item_id`)."},"leadGenFormId":{"type":"string","description":"Meta: the instant form the call to action opens (`call_to_action.value.lead_gen_form_id`, or the asset feed's `call_to_actions` on a dynamic creative), the same value as the `leadGenFormId` create input. Absent on ads without a lead form."},"imageHash":{"type":"string","description":"Meta: the ad image hash (`image_hash`), reusable as `imageHash` on POST /v1/ads/create within the same ad account. `thumbnailUrl` and `mediaUrls` carry its stable full resolution permalink when Meta resolves it."},"urlTags":{"type":["string","null"],"description":"Meta: the creative's `url_tags` query string appended to the destination URL."},"finalUrls":{"type":"array","minItems":1,"items":{"type":"string","format":"uri"},"description":"Google RSA only. Replaces final URLs. Omitted lists stay unchanged."},"thumbnailUrl":{"type":["string","null"],"description":"Primary thumbnail/image URL"},"imageUrl":{"type":"string","description":"Alternative image URL"},"assetResourceName":{"type":"string","description":"Google Display only. Resource name of the landscape marketing image asset (`creative.imageUrl`), for example customers/1234567890/assets/123. Set at creation and updated when PUT /v1/ads/{adId} replaces `creative.imageUrl`; replacing only `creative.squareImageUrl` leaves it unchanged."},"assets":{"type":"object","description":"Google Display only. Native Google asset resource name of each image on the responsive display ad, keyed by Google's image role. Set at creation for ads created through Zernio. PUT /v1/ads/{adId} overwrites only the role it replaces: `creative.imageUrl` updates `marketingImages`, `creative.squareImageUrl` updates `squareMarketingImages`. Absent on ads synced from Google.","properties":{"marketingImages":{"type":"array","description":"Landscape (1.91:1) marketing images. The first item matches `assetResourceName`.","items":{"type":"object","properties":{"resourceName":{"type":"string","description":"Google asset resource name, for example customers/1234567890/assets/123."}}}},"squareMarketingImages":{"type":"array","description":"Square (1:1) marketing images.","items":{"type":"object","properties":{"resourceName":{"type":"string","description":"Google asset resource name, for example customers/1234567890/assets/124."}}}}}},"videoId":{"type":["string","null"],"description":"Meta video ID for VIDEO-type ads (TikTok: the ad library `video_id`). 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."},"creativeId":{"type":["string","null"],"description":"Meta ad creative id backing this ad, refreshed from Meta on every sync. Reusable via existingCreativeId on POST /v1/ads/create, and readable raw through GET /v1/ads/creatives/{creativeId}. Ads synced from Meta also carry it as the legacy `id` key."},"creativeFeatures":{"$ref":"#/components/schemas/MetaCreativeFeatures","description":"Meta only. The creativeFeatures map sent at creation (degrees_of_freedom_spec.creative_features_spec). Absent on ads synced from Meta."},"catalog":{"type":"object","description":"Meta catalog template ads created through Zernio only (absent on ads synced from Meta).","properties":{"productSetId":{"type":"string","description":"The creative's product_set_id."},"format":{"type":"string","enum":["single_image","carousel_images_multi_items","carousel_images_single_item","carousel_slideshows"],"description":"object_story_spec.template_data.format_option, from catalogFormat."},"formatTransformationSpec":{"type":"array","description":"The format_transformation_spec sent on the creative, as Meta's raw objects. Present for single_image.","items":{"type":"object","properties":{"format":{"type":"string"},"data_source":{"type":"array","items":{"type":"string"}}}}}}},"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, because Meta omits it for SHARE creatives. Use effectiveObjectStoryId instead."},"effectiveObjectStoryId":{"type":["string","null"],"description":"Meta `effective_object_story_id`, the `{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`, the 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)."},"carouselCards":{"type":"array","description":"Meta only today. The carousel's cards in display order, one per Meta `link_data.child_attachments` entry, using the same field names as the `carouselCards` create input. Absent on non-carousel ads and other platforms.\n\n- Synced from Meta: `imageUrl` is resolved exactly like `mediaUrls` (the stable `/adimages` permalink first), so cards with an image line up with `mediaUrls` in order. A card whose image Meta does not resolve keeps its place without `imageUrl`.\n- Created through Zernio: starts as the cards you sent.\n- Synced carousels stored before this field existed fill it in on their next sync.\n","items":{"type":"object","properties":{"imageUrl":{"type":"string","description":"Card image, resolved like the matching `mediaUrls` entry. Absent when Meta returns no resolvable image for the card."},"imageHash":{"type":"string","description":"Meta ad image hash of the card image (`image_hash`)."},"headline":{"type":"string","description":"Card title (Meta `name`)."},"description":{"type":"string","description":"Card description, under the title (Meta `description`)."},"linkUrl":{"type":"string","description":"Card destination URL (Meta `link`)."},"callToAction":{"type":"string","description":"Card call to action type (Meta `call_to_action.type`), e.g. SHOP_NOW or WATCH_MORE.","example":"SHOP_NOW"},"videoId":{"type":"string","description":"Meta video id when the card is a video (`video_id`)."}}}},"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."},"adFormat":{"type":["string","null"],"description":"LinkedIn (and TikTok with `live=true`). The LinkedIn ad format, in LinkedIn's own vocabulary: STANDARD_UPDATE, SINGLE_VIDEO, CAROUSEL, NATIVE_DOCUMENT, EVENT, TEXT_AD, SPOTLIGHT, FOLLOW_COMPANY, JOBS, SPONSORED_INMAILS and others. The list is open, so treat an unrecognized value as valid.\n\n- On an ad Zernio created: the format it was created as.\n- On an ad synced from Campaign Manager: the parent campaign's raw `format`, which is what LinkedIn actually enforces on its creatives.\n\nAbsent on LinkedIn ads not yet re-synced. On TikTok with `live=true`: the ad's `ad_format` (e.g. SINGLE_VIDEO). Absent on every other platform."},"servingHoldReasons":{"type":"array","items":{"type":"string"},"description":"LinkedIn only. Why this specific creative is not being served. Empty when it is serving.\n\nA superset of the ad-level `servingStatuses`: it repeats the inherited campaign, campaign group and account holds AND adds creative-only causes, such as:\n\n- UNDER_REVIEW, REJECTED, PROCESSING, PROCESSING_FAILED;\n- FORM_HOLD (lead-gen-form creatives);\n- REFERRED_CONTENT_QUALITY_HOLD;\n- JOB_POSTING_ON_HOLD and JOB_POSTING_INVALID (job ads).\n\nSome 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.\n","example":["UNDER_REVIEW"]},"body":{"type":"string","description":"Ad copy/text"},"googleHeadline":{"type":"string","description":"Google Ads headline"},"googleDescription":{"type":"string","description":"Google Ads description"},"youtubeVideoIds":{"type":"array","items":{"type":"string"},"description":"Google only. YouTube video ids behind a Video campaign ad (video and responsive video ads) or a Demand Gen video ad, same id as `youtubeVideoId` on Performance Max asset groups. When the ad has no image, `thumbnailUrl` is the first video's YouTube thumbnail. Absent on ads without a video."},"linkUrl":{"type":"string","description":"Destination URL"},"whatsappPhoneNumber":{"type":"string","description":"Explicit E.164 WhatsApp number supplied when creating a Meta boost or messaging ad. Absent when omitted by the caller or on older records.","example":"+12025550123"},"instagramVideoFallback":{"$ref":"#/components/schemas/InstagramVideoFallback"},"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). May be absent if the ad set exposes no targeting or the lookup fails.\n\n- Ads created through Zernio: the spec you supplied.\n- External ads (synced from Meta Ads Manager, `isExternal: true`): targeting lives at the ad set and isn't stored at ingest. On the first `GET /v1/ads/{adId}` Zernio resolves it live from Meta and caches it on the ad.\n- External ads, value shape: Meta's raw `targeting` shape (snake_case, e.g. `geo_locations`, `age_min`), the same object Ads Manager shows.\n"},"schedule":{"type":["object","null"],"description":"Delivery window as UTC instants. For ads created through Zernio this is the start and end the platform stored (on TikTok, read back from the ad group, whose schedule times TikTok keeps in UTC); `startDate` is the creation time only when no start was requested.","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. Reads `paused` when the synced ad set or its campaign is switched off on the platform, even while the ads still report their own switch as on."},"schedule":{"type":["object","null"],"description":"The ad set's start and end as last synced from the platform, as UTC instants. Null when the ad set was never synced or has no schedule (on Pinterest under a CBO campaign, the end date sits on the campaign).","properties":{"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"}}},"createdTime":{"type":["string","null"],"format":"date-time","description":"Earliest `platformCreatedAt` (platform ad creation time; falls back to `createdAt`, Zernio's sync time, for ads synced before that field existed) across this ad set's ads. Not the ad set's own creation time on the platform, but a proxy usable for sorting."},"adCount":{"type":"integer"},"isSmartPlus":{"type":"boolean","description":"TikTok only. true when this ad group belongs to an Upgraded Smart+ campaign. See AdTreeCampaign.isSmartPlus."},"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"]},"daily":{"type":"number","description":"LinkedIn and X only. The daily budget (LinkedIn: the campaign's `dailyBudget`; X: the line item's `daily_budget_amount_local_micro`). Both allow a daily AND a lifetime budget together, which `amount`/`type` cannot express (daily wins there); read `daily` and `lifetime` to see both."},"lifetime":{"type":"number","description":"LinkedIn and X only. The lifetime total (LinkedIn: the campaign's `totalBudget`; X: the line item's `total_budget_amount_local_micro`), readable even when a daily budget is also set."},"pacing":{"type":"string","description":"LinkedIn only. The campaign's `pacingStrategy`: how fast LinkedIn may spend the budget. Typically LINEAR or ACCELERATED; the list is open."}}},"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"]},"daily":{"type":"number","description":"LinkedIn only. See `budget.daily`."},"lifetime":{"type":"number","description":"LinkedIn only. See `budget.lifetime`."},"pacing":{"type":"string","description":"LinkedIn only. See `budget.pacing`."}}},"metrics":{"$ref":"#/components/schemas/AdMetrics"},"previousMetrics":{"allOf":[{"$ref":"#/components/schemas/AdMetrics"}],"description":"Only with `compare=previous`. The same metrics over `previousRange`."},"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 apply.\n\n- Empty: no serving data.\n- [\"RUNNABLE\"]: eligible to serve.\n- Anything else: a hold. See the `servingStatuses` field on `Ad` for the known values.\n","example":["RUNNABLE"]},"learningStatus":{"type":["string","null"],"enum":["LEARNING","SUCCESS","FAIL",null],"description":"Meta only. Where the ad set stands in Meta's learning phase, as of the last sync. Null on other platforms and for ad sets not yet synced.\n\n- LEARNING: delivery is still being optimized (about 50 optimization events in 7 days end it).\n- SUCCESS: it has left learning.\n- FAIL: it could not gather enough events (Ads Manager's \"Learning limited\").\n"},"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"}}},"destinationType":{"type":["string","null"],"description":"Meta only. Where the ad set sends people (Meta `destination_type`), e.g. WEBSITE, MESSENGER, WHATSAPP, INSTAGRAM_DIRECT, ON_AD. Meta answers UNDEFINED for an ad set with no explicit destination. As of the last sync; null on other platforms and for ad sets not yet synced.","example":"WEBSITE"},"attributionSpec":{"type":["array","null"],"description":"Meta only. The ad set's conversion attribution windows (Meta `attribution_spec`), in the same shape `attributionSpec` takes on ad creation so a clone can send it back unchanged. As of the last sync; null on other platforms, for ad sets not yet synced and when Meta reports none.","items":{"type":"object","properties":{"eventType":{"type":"string","enum":["CLICK_THROUGH","VIEW_THROUGH","ENGAGED_VIDEO_VIEW"]},"windowDays":{"type":"integer","enum":[1,7,28]}}},"example":[{"eventType":"CLICK_THROUGH","windowDays":7},{"eventType":"VIEW_THROUGH","windowDays":1}]},"regionalRegulatedCategories":{"type":["array","null"],"description":"Meta only. Regional regulated categories declared on the ad set (Meta `regional_regulated_categories`), e.g. AUSTRALIA_FINSERV, TAIWAN_UNIVERSAL, SINGAPORE_UNIVERSAL or VOLUNTARY_VERIFICATION. As of the last sync; null on other platforms, for ad sets not yet synced and when Meta reports none.","items":{"type":"string"},"example":["AUSTRALIA_FINSERV"]},"regionalRegulationIdentities":{"type":["object","null"],"description":"Meta only. Verified identity IDs per regional regulation role (Meta `regional_regulation_identities`), keyed by Meta's role name. IDs are strings because they can exceed a JSON number's precision. As of the last sync; null on other platforms, for ad sets not yet synced and when Meta reports none.","additionalProperties":{"type":"string"},"example":{"australia_finserv_beneficiary":"28663624249921857","australia_finserv_payer":"28663624249921857"}},"ads":{"type":"array","items":{"$ref":"#/components/schemas/Ad"},"description":"Individual ads within this ad set (capped at 100). With more than 100 ads these are the 100 highest-spending over the requested date range, so the array depends on `fromDate`/`toDate`. `adCount` is always the true ad set size.\n\nA subset of Ad fields from the aggregation. Always included: `_id`, `name`, `platform`, `status`, `configuredStatus`, `reviewStatus`, `budget`, `metrics`, `creative`, `goal` and the `platform*` ids. `targeting` and `schedule` may be absent.\n\n`configuredStatus` (the ad's own on/off toggle) and `reviewStatus` (the platform's review verdict) are part of this contract, not incidental: only `reviewStatus` distinguishes a rejected ad from a healthy one.\n\nWhen `timeIncrement=1&dailyLevel=ad`, each entry also carries a `daily[]` array of `AdDailyMetrics`.\n"},"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":{"results":{"type":"object","additionalProperties":{"type":"number"},"description":"Only with `results=true`. The values you sent for this campaign over the range, plus each formula they allow, by metric key. A metric with no value is absent.","example":{"revenue":7800,"sales":4,"cac_percent":31.2,"cost_per_sale":608.5}},"platformCampaignId":{"type":"string"},"platform":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit","microsoft"]},"campaignName":{"type":"string"},"createdTime":{"type":["string","null"],"format":"date-time","description":"Earliest `platformCreatedAt` across every ad in the campaign (platform ad creation time; falls back to `createdAt`, Zernio's sync time, for ads synced before that field existed).\n\nNot the platform campaign's own creation time (Meta's `Campaign.created_time` etc. is not synced). A campaign created empty and populated later shows its first ad's time, not the campaign's.\n\nUsable for sorting \"most recently created\" without the numeric-campaign-id heuristic. Same source as `AdTreeAdSet.createdTime` and `Ad.platformCreatedAt`; mirrors `AdCampaign.earliestAd`.\n"},"status":{"allOf":[{"$ref":"#/components/schemas/AdStatus"}],"description":"Delivery status derived from child ad statuses. Reads `paused` when the campaign is switched off on the platform (`platformCampaignStatus`), even while its ads still report their own switch as on. Distinct from `reviewStatus`, which reflects the platform-side review state."},"schedule":{"type":["object","null"],"description":"The campaign's start and end as last synced from the platform, as UTC instants. Null when the campaign was never synced or has no schedule. Where the platform schedules the ad set instead (Meta, TikTok), read `AdTreeAdSet.schedule`.","properties":{"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"}}},"reviewStatus":{"anyOf":[{"$ref":"#/components/schemas/AdReviewStatus"},{"type":"null"}],"description":"Platform-side review state of the campaign. Independent of the\nchildren-derived delivery `status`: a campaign can have ads\nalready active (status=active) while the campaign itself is\nstill being reviewed by the platform (reviewStatus=in_review).\nFor Meta, derived from `effective_status` + `issues_info` on\nthe Campaign, plus ad-level PENDING_REVIEW rollup.\n"},"platformCampaignStatus":{"type":["string","null"],"description":"Raw platform-level campaign status (Meta `effective_status`: ACTIVE, PAUSED, DELETED, ARCHIVED, IN_PROCESS, WITH_ISSUES; ChatGPT (OpenAI): the campaign's own switch, active / paused / archived, independent of the delivery `status`; TikTok: the campaign's own switch `operation_status`, ENABLE / DISABLE; Reddit: the campaign's `configured_status`, ACTIVE / PAUSED / ARCHIVED). 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"},"previousMetrics":{"allOf":[{"$ref":"#/components/schemas/AdMetrics"}],"description":"Only with `compare=previous`. The same metrics over `previousRange`."},"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","description":"Profile the row belongs to: the profile of its owning connection (`accountId`); when that connection no longer exists, the requested profile (`profileId` filter) that reaches the row ad account, else the profile of the oldest connection of the row owner that reaches it."},"isSmartPlus":{"type":"boolean","description":"TikTok only. true when the campaign is an Upgraded Smart+ campaign (TikTok lists it on /smart_plus/campaign/get/), false when it is not.\n\nSet by ads sync, so the key is absent on other platforms and on TikTok campaigns not synced since this field shipped.\n\nOn Smart+ objects Zernio can pause, resume, rename, delete and change the budget of the campaign and ad set, and pause or resume an ad. Other edits answer 422 and belong in TikTok Ads Manager."},"advertisingChannelType":{"type":["string","null"],"description":"Google-only. Raw campaign.advertising_channel_type (SEARCH, PERFORMANCE_MAX, LOCAL_SERVICES, 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":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"The ad sets' optimization goal.\n\n- A single string when every ad set shares one goal.\n- A JSON array of the distinct goals when ad sets differ (never a comma-joined string). Element order is not guaranteed; treat it as an unordered set.\n- Absent when no ad set carries a goal.\n\nMeta: 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.\n"},"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"}}},"specialAdCategories":{"type":"array","items":{"type":"string"},"description":"Special ad categories declared when Zernio created the campaign, read from the ad that created it (its earliest ad), e.g. [\"HOUSING\"]. Absent when none was declared or the campaign was created outside Zernio."},"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","reddit","microsoft"]},"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`; ChatGPT (OpenAI): the campaign's own switch, active / paused / archived; TikTok: the campaign's own switch `operation_status`, ENABLE / DISABLE; Reddit: the campaign's `configured_status`, ACTIVE / PAUSED / ARCHIVED)."},"statusReadAt":{"type":["string","null"],"format":"date-time","description":"Only on GET /v1/ads/campaigns with `live=true`. When `platformCampaignStatus` was read from the platform; null when this campaign could not be read live."},"nativeSettings":{"type":"object","additionalProperties":true,"description":"TikTok only, only on GET /v1/ads/campaigns with `live=true` and only on campaigns read live. A fixed subset of TikTok's campaign/get record, not the whole record, each field with TikTok's own value and present only when TikTok returns it:\n\n- campaign_id, operation_status, objective_type\n- budget_mode (BUDGET_MODE_INFINITE means no campaign budget, so budget lives on the ad groups)\n- budget and budget_optimize_on\n\nPlus advertiser_currency and advertiser_timezone from TikTok's advertiser/info. Whether the campaign is Upgraded Smart+ is `isSmartPlus`.\n"},"configReadAt":{"type":["string","null"],"format":"date-time","description":"Only on GET /v1/ads/campaigns with `live=true`. When `nativeSettings` was read from the platform. Null whenever native settings were not read now."},"campaignIssuesInfo":{"type":["array","null"],"description":"Platform-reported campaign issues (Meta `issues_info[]`).","items":{"type":"object"}},"adCount":{"type":"integer"},"budget":{"anyOf":[{"$ref":"#/components/schemas/AdCampaignBudget"},{"type":"null"}],"description":"Effective budget. Google metadata arrives after the next successful sync."},"campaignBudget":{"anyOf":[{"$ref":"#/components/schemas/AdCampaignBudget"},{"type":"null"}],"description":"Campaign-level budget. Null for ad-set budgets."},"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","description":"Profile the row belongs to: the profile of its owning connection (`accountId`); when that connection no longer exists, the requested profile (`profileId` filter) that reaches the row ad account, else the profile of the oldest connection of the row owner that reaches it."},"isSmartPlus":{"type":"boolean","description":"TikTok only. true when the campaign is an Upgraded Smart+ campaign. See AdTreeCampaign.isSmartPlus."},"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":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"The campaign's optimization goal.\n\n- Every ad set shares one goal: a single string.\n- Ad sets differ: a JSON array of the distinct goals (never a comma-joined string). Element order is not guaranteed; treat it as an unordered set.\n- No ad set carries a goal: the key is absent.\n\n**Values:**\n\n- Meta: e.g. OFFSITE_CONVERSIONS, VALUE, LEAD_GENERATION.\n- LinkedIn: the campaign optimizationTargetType (e.g. MAX_CLICK, MAX_IMPRESSION, NONE). `NONE` with a manual costType is a campaign LinkedIn will not deliver.\n"},"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"}}},"specialAdCategories":{"type":"array","items":{"type":"string"},"description":"Special ad categories declared when Zernio created the campaign, read from the ad that created it (its earliest ad), e.g. [\"HOUSING\"]. Absent when none was declared or the campaign was created outside Zernio."},"earliestAd":{"type":"string","format":"date-time"},"latestAd":{"type":"string","format":"date-time"}}},"GoogleAdLabel":{"type":"object","properties":{"id":{"type":"string","description":"Google label id"},"resourceName":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["ENABLED","REMOVED","UNKNOWN"]},"backgroundColor":{"type":["string","null"],"description":"#RRGGBB"},"description":{"type":["string","null"],"description":"Null when empty."}}},"GoogleAdLabelAssignments":{"type":"object","additionalProperties":false,"required":["accountId"],"description":"At least one id across the four target lists. Up to 1000 ids per list.","properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id (Google Ads)"},"adAccountId":{"type":"string","pattern":"^\\d+$","description":"Google customer id. Required when the connection has multiple customers."},"customerId":{"type":"string","pattern":"^\\d+$","deprecated":true,"description":"Alias of adAccountId"},"campaignIds":{"type":"array","maxItems":1000,"items":{"type":"string","pattern":"^\\d+$"},"description":"Google campaign ids"},"adSetIds":{"type":"array","maxItems":1000,"items":{"type":"string","pattern":"^\\d+$"},"description":"Google ad group ids"},"adIds":{"type":"array","maxItems":1000,"items":{"type":"string","pattern":"^\\d+~\\d+$"},"description":"Google ad group ad ids, {adGroupId}~{adId}"},"keywordIds":{"type":"array","maxItems":1000,"items":{"type":"string","pattern":"^\\d+~\\d+$"},"description":"Google keyword criterion ids, {adGroupId}~{criterionId}"}}},"GoogleBiddableGoalInput":{"type":"object","additionalProperties":false,"required":["category","origin","biddable"],"properties":{"category":{"type":"string","pattern":"^[A-Z][A-Z0-9_]*$","description":"Google ConversionActionCategory, e.g. PURCHASE, SIGNUP, SUBMIT_LEAD_FORM"},"origin":{"type":"string","pattern":"^[A-Z][A-Z0-9_]*$","description":"Google ConversionOrigin, e.g. WEBSITE, APP, CALL_FROM_ADS, STORE, GOOGLE_HOSTED"},"biddable":{"type":"boolean"}}},"GoogleCustomerConversionGoal":{"type":"object","properties":{"category":{"type":"string"},"origin":{"type":"string"},"biddable":{"type":"boolean","description":"Used for bidding and counted in the Conversions column."},"resourceName":{"type":"string"},"conversionActions":{"type":"array","description":"Non-removed conversion actions in this category and origin.","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"primaryForGoal":{"type":"boolean","description":"true = primary, false = secondary"}}}}}},"GoogleCampaignConversionGoals":{"type":"object","properties":{"campaignId":{"type":"string"},"goalConfigLevel":{"type":"string","enum":["CUSTOMER","CAMPAIGN","UNSPECIFIED","UNKNOWN"]},"customConversionGoalId":{"type":["string","null"]},"goals":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"origin":{"type":"string"},"biddable":{"type":"boolean"},"resourceName":{"type":"string"}}}}}},"GoogleCustomConversionGoal":{"type":"object","properties":{"id":{"type":"string"},"resourceName":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"conversionActionIds":{"type":"array","items":{"type":"string"}}}},"CampaignResultMetric":{"type":"object","required":["key","label","kind","currency","formula","builtIn"],"properties":{"key":{"type":"string","example":"qualified_leads"},"label":{"type":"string","example":"Qualified leads"},"kind":{"type":"string","enum":["count","money","percent","ratio"],"description":"How the value reads: `percent` values are already multiplied by 100."},"currency":{"type":["string","null"]},"formula":{"type":["string","null"],"description":"Null for a number you send. For a computed metric, the formula over `spend`, `impressions`, `clicks`, `conversions`, `purchase_value` and the metrics you send, e.g. `spend / revenue * 100`.","example":null},"builtIn":{"type":"boolean","description":"One of the formulas every team has (`cac_percent`, `cost_per_sale`, `cost_per_qualified_lead`, `lead_to_sale`). Setting the same key replaces it for your team."}}},"AdRuleLevel":{"type":"string","enum":["campaign","adset","ad"],"description":"Whether the rule checks campaigns, ad sets or single ads. Each one is evaluated on its own."},"AdRuleCondition":{"type":"object","required":["metric","window","op","value"],"properties":{"metric":{"type":"string","anyOf":[{"enum":["spend","impressions","clicks","conversions","ctr","cpc","cpm","cpa","roas","reach","frequency","daily_budget","budget_used","day_of_month","working_day_of_month"]},{"pattern":"^result:[a-z][a-z0-9_]{0,39}$"}],"description":"`ctr` is a percentage. `spend`, `cpc`, `cpm` and `cpa` are in the ad account currency. `reach` and `frequency` use the platform's de-duplicated reach, so they are accepted on Meta and TikTok only.\n\n`daily_budget` is the object's synced daily budget. `budget_used` is spend over the window as a percent of that budget for each day of the window: `today` `>=` 200 means twice the budget spent.\n\nBoth read campaigns and ad sets with a daily budget of their own. A lifetime budget never matches.\n\n`day_of_month` and `working_day_of_month` read today's date in the ad account's timezone, the same for every object: `working_day_of_month` `>=` 5 holds from the fifth weekday of the month (Monday to Friday, holidays not counted). They take `window: today`, no `compareTo` and no `top` or `bottom`.\n\n`result:<key>` reads one of your own results (see [Campaign results](/guides/campaign-results)), on campaign rules only: the values you sent for the window, or a formula over them and the platform's numbers. A campaign with no value for it never matches.\n","example":"result:cac_percent"},"window":{"type":"string","anyOf":[{"enum":["today","yesterday","last_3d","last_7d","last_14d","last_30d","this_month","last_month"]},{"pattern":"^[0-9]{1,2}_to_[0-9]{1,2}_days_ago$"}],"description":"Days in the ad account's own timezone. `last_7d` is the 7 full days before today; only `today` and `this_month` read the day in progress.\n\n`this_month` runs from the 1st through today; `last_month` is the whole previous calendar month.\n\n`<from>_to_<to>_days_ago` is any range of full days, both ends included, such as `8_to_2_days_ago` to skip the 2 most recent days while their conversions still arrive. `from` is at least `to` and at most 90.\n","example":"last_7d"},"op":{"type":"string","enum":[">",">=","<","<=","top","bottom"],"description":"`top` and `bottom` rank the rule's objects by the metric over the window, highest first for `top`, and match the first `value` (a whole number from 1 to 100). Objects with no value are not ranked; the run history shows each one's position."},"value":{"type":"number","minimum":0},"compareTo":{"type":"string","description":"Makes the condition relative: `value` becomes a ratio of the metric over `window` to the same metric over this window, such as `30_to_2_days_ago`.\n\n`previous_period` is the same number of days just before `window`. For `this_month` it is the same days of last month, and for `last_month` the month before.\n\nSpend, impressions, clicks, conversions and reach are compared per day, so windows of different lengths compare fairly; rates such as `cpc` compare as they are. A comparison window with no value never matches.\n","example":"previous_period"}}},"AdRuleConditions":{"description":"A group: `all` (every item must hold) or `any` (one is enough). An item is a condition or another group, nested up to 3 levels, with at most 10 conditions in total. A rate with no denominator (a CPA with no conversions) never matches.\n","oneOf":[{"type":"object","required":["all"],"additionalProperties":false,"properties":{"all":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/AdRuleConditionItem"}}}},{"type":"object","required":["any"],"additionalProperties":false,"properties":{"any":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/AdRuleConditionItem"}}}}],"example":{"any":[{"metric":"cpc","window":"today","op":">","value":2},{"all":[{"metric":"spend","window":"today","op":">=","value":50},{"metric":"conversions","window":"today","op":"<","value":1}]}]}},"AdRuleConditionItem":{"oneOf":[{"$ref":"#/components/schemas/AdRuleCondition"},{"$ref":"#/components/schemas/AdRuleConditions"}]},"AdRuleAction":{"oneOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["notify"],"description":"Send the `ad_rule.triggered` webhook, and the alert to every `send` destination."},"send":{"type":"array","minItems":1,"maxItems":5,"description":"Also send a short alert through accounts you connected: what matched, the values and what the rule did. Up to 5 destinations, checked when the rule is saved.\n\nA destination that fails is reported in the run's `notification`; it never undoes a change.\n","items":{"oneOf":[{"type":"object","required":["accountId"],"additionalProperties":false,"properties":{"accountId":{"type":"string","description":"A connected Slack account (`GET /v1/accounts`, platform `slack`)."},"channelId":{"type":"string","description":"The Slack channel to post in. Defaults to the channel the account was connected with; the bot joins public channels on its own."}}},{"type":"object","required":["accountId","to"],"additionalProperties":false,"properties":{"accountId":{"type":"string","description":"A connected Gmail or Outlook mailbox with email access."},"to":{"type":"string","format":"email","description":"The address that receives the alert, sent as a new email from that mailbox."}}}]}}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["pause"],"description":"Pause the campaign, ad set or ad."},"maxChangesPerDay":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many objects changed in any 24 hours, across runs. Matches over the limit are skipped with `daily_limit_reached` and tried again later."},"maxChangesPerObject":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many changes to one object by this rule, counted over the last 400 days. An object at the limit is left alone like one in cooldown."}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["activate"],"description":"Reactivate a campaign, ad set or ad a rule paused, once `cooldownMinutes` has passed since the pause. Objects you paused yourself are left alone unless `includeManuallyPaused` is true."},"includeManuallyPaused":{"type":"boolean","description":"Also reactivate paused objects that no rule paused, as soon as they match."},"maxChangesPerDay":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many objects changed in any 24 hours, across runs. Matches over the limit are skipped with `daily_limit_reached` and tried again later."},"maxChangesPerObject":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many changes to one object by this rule, counted over the last 400 days. An object at the limit is left alone like one in cooldown."}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["duplicate"],"description":"Copy the campaign or ad set with its ads, on Meta and TikTok campaigns and ad sets and LinkedIn campaigns. Not on ad-level rules."},"status":{"type":"string","enum":["paused","active"],"description":"How the copy starts. Defaults to `paused`."},"renameSuffix":{"type":"string","maxLength":50,"description":"Text added to the copy's name."},"maxChangesPerDay":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many objects changed in any 24 hours, across runs. Matches over the limit are skipped with `daily_limit_reached` and tried again later."},"maxChangesPerObject":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many changes to one object by this rule, counted over the last 400 days. An object at the limit is left alone like one in cooldown."}}},{"type":"object","required":["type"],"description":"Either `amount`, or `direction`, `percent` and `limit`.","properties":{"type":{"type":"string","enum":["adjust_bid"],"description":"Move the bid cap or cost cap of a Meta ad set, in the ad account currency. Ad set rules on Meta only. An ad set without a cap is skipped with `no_bid_cap`."},"amount":{"type":"number","exclusiveMinimum":0,"description":"The cap to set."},"direction":{"type":"string","enum":["increase","decrease"]},"percent":{"type":"integer","minimum":1,"maximum":100,"description":"Step size. A decrease is at most 90."},"limit":{"type":"number","exclusiveMinimum":0,"description":"The cap never goes above this on an increase, or below it on a decrease."},"maxChangesPerDay":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many objects changed in any 24 hours, across runs. Matches over the limit are skipped with `daily_limit_reached` and tried again later."},"maxChangesPerObject":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many changes to one object by this rule, counted over the last 400 days. An object at the limit is left alone like one in cooldown."}}},{"type":"object","required":["type","target"],"description":"Either `amount`, or `direction`, `percent` and `limit`.","properties":{"type":{"type":"string","enum":["adjust_target"],"description":"Move a Google campaign's target CPA or target ROAS inside the strategy it is on (Target CPA or Maximize conversions for `cpa`, Target ROAS or Maximize conversion value for `roas`), never switching strategies. Campaign rules on Google only.\n\nSkipped with `portfolio_bid_strategy` on a portfolio strategy, `unsupported_bid_strategy` on one with no target (Manual CPC, Maximize clicks), and `no_target_cpa` or `no_target_roas` when the strategy holds no such target. A target CPA in a zero-decimal currency is rounded to whole units."},"target":{"type":"string","enum":["cpa","roas"],"description":"Which target moves: `cpa` in the ad account currency, `roas` as a ratio (3 is 300%)."},"amount":{"type":"number","exclusiveMinimum":0,"description":"The target to set."},"direction":{"type":"string","enum":["increase","decrease"]},"percent":{"type":"integer","minimum":1,"maximum":100,"description":"Step size. A decrease is at most 90."},"limit":{"type":"number","exclusiveMinimum":0,"description":"The target never goes above this on an increase, or below it on a decrease."},"maxChangesPerDay":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many objects changed in any 24 hours, across runs. Matches over the limit are skipped with `daily_limit_reached` and tried again later."},"maxChangesPerObject":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many changes to one object by this rule, counted over the last 400 days. An object at the limit is left alone like one in cooldown."}}},{"type":"object","required":["type","metric","window","from","to"],"description":"Exactly one of `percent` and `amount`.","properties":{"type":{"type":"string","enum":["reallocate_budget"],"description":"Move daily budget from the matched objects ranked worst by `metric` to those ranked best, keeping the total the same. Not with `lifecycle` or `groups`.\n\nCampaign or ad set rules where the budget sits at that level: objects whose budget sits at another level (Meta CBO and ad set budgets), Google shared budgets and lifetime budgets are left out.\n\nChanges are reserved all at once: when `maxChangesPerDay` would hold back any of them, none is made. A receiver is raised only after every giver's cut applied (else it fails with `reallocation_incomplete` and the move is tried again next run).\n\nAmounts move in the currency's smallest unit (whole units for JPY or KRW). Counts as raising live spend for the free ads allowance."},"metric":{"type":"string","description":"What objects are ranked by: any condition metric except `day_of_month` and `working_day_of_month`, or a result metric (`result:<key>`) on campaign rules.\n\nObjects without a value are not ranked, except one that spent with no result on a metric where lower is best (a CPA with no conversions): it ranks worst and only gives."},"window":{"type":"string","description":"The period the metric is read over, like a condition window."},"best":{"type":"string","enum":["highest","lowest"],"description":"Which end of the ranking is best. Defaults to `lowest` for `cpa`, `cpc`, `cpm`, `frequency` and result metrics whose formula has spend above the line (cost per sale, %CAC), `highest` otherwise."},"from":{"type":"object","required":["count"],"properties":{"count":{"type":"integer","minimum":1,"maximum":10}},"description":"How many of the worst-ranked objects give budget."},"to":{"type":"object","required":["count"],"properties":{"count":{"type":"integer","minimum":1,"maximum":10}},"description":"How many of the best-ranked objects receive it. With fewer ranked objects than `from` plus `to`, givers take at most half and no object is on both sides."},"percent":{"type":"integer","minimum":1,"maximum":90,"description":"The share of each giver's daily budget it gives."},"amount":{"type":"number","exclusiveMinimum":0,"description":"The total to move each run, in the ad account currency, taken evenly from the givers."},"minBudget":{"type":"number","exclusiveMinimum":0,"description":"A giver never goes below this daily budget. A giver also always keeps a tenth of its budget."},"maxBudget":{"type":"number","exclusiveMinimum":0,"description":"A receiver never goes above this daily budget; what receivers cannot take stays with the givers."},"maxChangesPerDay":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many objects changed in any 24 hours, across runs. Matches over the limit are skipped with `daily_limit_reached` and tried again later."},"maxChangesPerObject":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many changes to one object by this rule, counted over the last 400 days. An object at the limit is left alone like one in cooldown."}}},{"type":"object","required":["type"],"description":"Exactly one of `add` and `remove`.","properties":{"type":{"type":"string","enum":["edit_name"],"description":"Tag the object by its name. Meta, TikTok and Reddit campaigns, ad sets and ads, and Google, LinkedIn and Pinterest campaigns and ad sets. An object whose name already has the tag (or lacks it, for `remove`) is skipped with `name_unchanged`."},"add":{"type":"string","minLength":1,"maxLength":50,"description":"Text to add, like `[WINNER]`. Compared without case."},"at":{"type":"string","enum":["start","end"],"description":"Where `add` goes. Defaults to `start`."},"remove":{"type":"string","minLength":1,"maxLength":50,"description":"Text to take out of the name, every copy of it."},"maxChangesPerDay":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many objects changed in any 24 hours, across runs. Matches over the limit are skipped with `daily_limit_reached` and tried again later."},"maxChangesPerObject":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many changes to one object by this rule, counted over the last 400 days. An object at the limit is left alone like one in cooldown."}}},{"type":"object","required":["type","amount"],"properties":{"type":{"type":"string","enum":["adjust_budget"],"description":"Set the daily budget to an exact amount, such as a reset every midnight. Same level rules as the percent change."},"amount":{"type":"number","exclusiveMinimum":0,"description":"The daily budget to set, in the ad account currency. An object already at it is skipped with `already_at_amount`."},"maxChangesPerDay":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many objects changed in any 24 hours, across runs. Matches over the limit are skipped with `daily_limit_reached` and tried again later."},"maxChangesPerObject":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many changes to one object by this rule, counted over the last 400 days. An object at the limit is left alone like one in cooldown."}}},{"type":"object","required":["type","direction","percent","limit"],"properties":{"type":{"type":"string","enum":["adjust_budget"],"description":"Change the daily budget. Not on ad-level rules (an ad has no budget), and on Google it needs a campaign-level rule (ad groups have no budget of their own)."},"direction":{"type":"string","enum":["increase","decrease"]},"percent":{"type":"integer","minimum":1,"maximum":100,"description":"Change in percent: up to 100 for an increase, up to 90 for a decrease."},"limit":{"type":"number","exclusiveMinimum":0,"description":"The budget never goes above this on an increase, or below it on a decrease, in the ad account currency."},"maxChangesPerDay":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many objects changed in any 24 hours, across runs. Matches over the limit are skipped with `daily_limit_reached` and tried again later."},"maxChangesPerObject":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many changes to one object by this rule, counted over the last 400 days. An object at the limit is left alone like one in cooldown."}}}]},"AdRuleActions":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/AdRuleAction"},"description":"Each type at most once, and at most one of `pause`, `activate`, `adjust_budget`, `adjust_bid`, `adjust_target`, `reallocate_budget`, `duplicate` and `edit_name`."},"AdRuleLifecycle":{"type":"object","description":"Turns matches into alerts. An object acts and notifies only after `confirmChecks` matching runs in a row; its alert stays open while it matches or `hold` holds, turns critical when `critical` holds, and resolves on its own. Cooldown and caps still decide repeat actions.","properties":{"confirmChecks":{"type":"integer","minimum":1,"maximum":5,"description":"Matching runs in a row before acting. Defaults to 1."},"hold":{"allOf":[{"$ref":"#/components/schemas/AdRuleConditions"}],"description":"Keeps an open alert open after the conditions stop matching."},"critical":{"allOf":[{"$ref":"#/components/schemas/AdRuleConditions"}],"description":"Marks an open alert critical."}}},"AdRuleGroups":{"type":["array","null"],"minItems":1,"maxItems":20,"description":"Campaigns judged together, campaign rules only. Each group's numbers and your results are added up across its campaigns, and rates and formulas are computed on the totals: a group's `result:cac_percent` is its total spend over its total revenue.\n\nThe conditions are judged once per group, and a matching group acts on each of its campaigns, each with its own cooldown and daily cap. Paused campaigns count toward a group's totals; only the ones the rule may act on are changed.\n\nA group with no filters holds every campaign the rule checks: the whole ad account. A campaign in several groups is acted on once per run, by the first matching group. Reach and frequency cannot be added up across campaigns, so a rule with groups cannot use them.\n\nA campaign with no results sent for the window adds its spend and no results to its group. A result sent as a rate (kind `percent` or `ratio`, no formula) reads as unknown for a group; define it as a formula over counts.\n","items":{"type":"object","required":["name","filters"],"properties":{"name":{"type":"string","minLength":1,"maxLength":60,"description":"Unique in the rule, ignoring case."},"filters":{"$ref":"#/components/schemas/AdRuleFilters"}}},"example":[{"name":"MBA","filters":[{"field":"name","op":"contains","value":"MBA"}]},{"name":"Account total","filters":[]}]},"AdRuleFilters":{"type":"array","maxItems":10,"description":"Narrows the objects the rule checks. Every filter must hold. A campaign rule reads `name`, `campaign_id`, `goal`, `days_live` and `budget_level`; an ad set rule also `campaign_name` and `adset_id`; an ad rule also `adset_name` and `ad_id`.","items":{"oneOf":[{"type":"object","title":"Name or goal","required":["field","op","value"],"description":"Compares without case; a missing name reads as empty.","properties":{"field":{"type":"string","enum":["name","campaign_name","adset_name","goal"],"description":"The object's own name, its campaign's or ad set's name, or the campaign goal (objective) as the platform reports it."},"op":{"type":"string","enum":["contains","not_contains","equals","not_equals","starts_with"]},"value":{"type":"string","minLength":1,"maxLength":200}}},{"type":"object","title":"Ids","required":["field","op","values"],"description":"Picks (`in`) or leaves out (`not_in`) campaigns, ad sets or ads by their platform ids.","properties":{"field":{"type":"string","enum":["campaign_id","adset_id","ad_id"]},"op":{"type":"string","enum":["in","not_in"]},"values":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1}}}},{"type":"object","title":"Budget level","required":["field","op","value"],"description":"Where the budget sits: on the campaign (Meta CBO, every Google campaign) or on each ad set (ABO). An object whose budget level is unknown never passes.","properties":{"field":{"type":"string","enum":["budget_level"]},"op":{"type":"string","enum":["equals"]},"value":{"type":"string","enum":["campaign","adset"]}}},{"type":"object","title":"Days live","required":["field","op","value"],"description":"Days since the object's first ad was created on the platform. An object without that date never passes.","properties":{"field":{"type":"string","enum":["days_live"]},"op":{"type":"string","enum":[">=","<"]},"value":{"type":"integer","minimum":0,"maximum":3650}}}]}},"AdRuleSchedule":{"type":"object","description":"Either `everyMinutes` or `times`. Sending a schedule replaces the rule's whole timing. Without one, a new rule runs every 60 minutes.","properties":{"everyMinutes":{"type":["integer","null"],"enum":[15,30,60,180,360,720,1440,null],"description":"How often the rule runs, in minutes. Null on a rule that runs at set times."},"times":{"type":["array","null"],"minItems":1,"maxItems":24,"description":"Set weekly times in the ad account timezone, instead of an interval. A rule that changes ads needs a cooldown of at least the shortest gap between two times.","items":{"type":"object","required":["days","at"],"properties":{"days":{"type":"array","minItems":1,"maxItems":7,"items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}},"at":{"type":"string","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","description":"Wall-clock time, 24-hour `HH:MM`.","example":"09:00"}}}},"startsAt":{"type":["string","null"],"format":"date-time","description":"The rule runs from this time on."},"endsAt":{"type":["string","null"],"format":"date-time","description":"The rule stops running after this time."},"quietHours":{"type":["object","null"],"required":["from","to"],"description":"A daily window in the ad account timezone when the rule does not run, like `{ \"from\": \"22:00\", \"to\": \"06:00\" }`. It may wrap past midnight; the first run after it comes on the next interval point or set time.","properties":{"from":{"type":"string","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"to":{"type":"string","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","example":"06:00"}}}}},"AutomationScheduleTrigger":{"type":"object","required":["type"],"additionalProperties":false,"description":"When an ad rule runs: `every` an interval or at set weekly `times` (send one), optionally only between `startsAt` and `endsAt` and never inside `quietHours`. Times and quiet hours are in the ad account timezone.\n","properties":{"type":{"type":"string","const":"schedule"},"every":{"type":"string","enum":["15m","30m","1h","3h","6h","12h","1d"],"description":"Run every interval. Send this or `times`, not both."},"times":{"type":"array","minItems":1,"maxItems":24,"description":"Set weekly times. Send this or `every`, not both.","items":{"type":"object","required":["days","at"],"additionalProperties":false,"properties":{"days":{"type":"array","minItems":1,"maxItems":7,"items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}},"at":{"type":"string","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","example":"09:00"}}}},"startsAt":{"type":"string","format":"date-time","description":"Runs from this time on."},"endsAt":{"type":"string","format":"date-time","description":"Stops running after this time. Must be after `startsAt`."},"quietHours":{"type":"object","required":["from","to"],"additionalProperties":false,"description":"A daily window with no checks. It may wrap past midnight, such as `22:00` to `06:00`.","properties":{"from":{"type":"string","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"to":{"type":"string","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","example":"06:00","description":"Differs from `from`."}}}}},"AutomationEventTrigger":{"type":"object","required":["type","profileId"],"additionalProperties":false,"description":"Starts the automation when something happens in Zernio, in one profile. `GET /v1/automations/catalog` lists every event with its facts.\n","properties":{"type":{"type":"string","description":"The Zernio event that starts it.","enum":["post.failed","post.partial","post.published","post.scheduled","post.recycled","post.platform.published","post.platform.failed","post.platform.deleted","post.external.created","account.connected","account.disconnected","account.permissions_changed","account.rate_limited","account.ads.sync_failed","ad.status_changed","ad.review.rejected","ad.delivery_issue","campaign.budget.depleted","ad_account.status_changed","whatsapp.template.status_updated","whatsapp.account.quality_updated","commerce.order.created","commerce.order.updated","commerce.order.refunded","message.received","message.failed","conversation.started","reaction.received","referral.received","comment.received","review.new","call.received","call.ended","call.failed","lead.received"],"example":"post.failed"},"profileId":{"type":"string","description":"The profile whose events start it, from `GET /v1/profiles`."},"accountIds":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string"},"description":"Only events of these accounts. Leave out for every account of the profile."},"filter":{"$ref":"#/components/schemas/AutomationFactCondition"}}},"AutomationPostSchedule":{"type":"object","required":["type","every"],"additionalProperties":false,"description":"When a scheduled automation checks its posts. Set times and quiet hours are not available for posts.","properties":{"type":{"type":"string","const":"schedule"},"every":{"type":"string","enum":["15m","30m","1h","3h","6h","12h","1d"]},"startsAt":{"type":"string","format":"date-time","description":"Runs from this time on."},"endsAt":{"type":"string","format":"date-time","description":"Stops running after this time."}}},"AutomationTrigger":{"description":"When the automation runs. Its shape decides the kind:\n\n- A Zernio event name in `type` makes an event automation.\n- A `schedule` over `subjects.each: post` makes a scheduled automation.\n- Any other `schedule` makes an ad rule.\n","oneOf":[{"$ref":"#/components/schemas/AutomationScheduleTrigger"},{"$ref":"#/components/schemas/AutomationEventTrigger"},{"$ref":"#/components/schemas/AutomationPostSchedule"}]},"AutomationFactCondition":{"description":"Narrows by the facts of the event or post, such as `platform` or `likes`: one comparison, or a group where `all` must hold or `any` is enough. Groups nest.\n\nA leaf whose `field` is not a fact of the event or post is refused. Text compares ignoring case. A number or date that does not parse never matches.\n","oneOf":[{"type":"object","required":["field","op","value"],"additionalProperties":false,"properties":{"field":{"type":"string","description":"A fact name from the catalog.","example":"platform"},"op":{"type":"string","enum":["equals","not_equals","contains","not_contains","starts_with","ends_with","exists","not_exists","matches","greater_than","less_than","greater_or_equal","less_or_equal","before","after","has_tag","not_has_tag","is_true","is_false"]},"value":{"type":["string","number"],"example":"instagram"}}},{"type":"object","required":["all"],"additionalProperties":false,"properties":{"all":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/AutomationFactCondition"}}}},{"type":"object","required":["any"],"additionalProperties":false,"properties":{"any":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/AutomationFactCondition"}}}}]},"AutomationAdFilter":{"description":"Narrows the ad objects checked, before any metric is read. `GET /v1/automations/catalog` lists the fields each subject accepts.\n","oneOf":[{"type":"object","required":["field","op","value"],"additionalProperties":false,"description":"Matches a name, a parent's name or the goal, ignoring case.","properties":{"field":{"type":"string","enum":["name","campaign_name","adset_name","goal"]},"op":{"type":"string","enum":["contains","not_contains","equals","not_equals","starts_with"]},"value":{"type":"string","minLength":1,"maxLength":200}}},{"type":"object","required":["field","op","values"],"additionalProperties":false,"description":"Picks or leaves out objects by platform ID.","properties":{"field":{"type":"string","enum":["campaign_id","adset_id","ad_id"]},"op":{"type":"string","enum":["in","not_in"]},"values":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string"}}}},{"type":"object","required":["field","op","value"],"additionalProperties":false,"description":"Days since the object's first ad was created, so new ads get time to learn.","properties":{"field":{"type":"string","const":"days_live"},"op":{"type":"string","enum":[">=","<"]},"value":{"type":"integer","minimum":0,"maximum":3650}}},{"type":"object","required":["field","op","value"],"additionalProperties":false,"description":"Where the budget sits: on the campaign (Meta CBO, every Google campaign) or on each ad set.","properties":{"field":{"type":"string","const":"budget_level"},"op":{"type":"string","const":"equals"},"value":{"type":"string","enum":["campaign","adset"]}}}]},"AutomationSubjects":{"type":"object","required":["each","adAccounts"],"description":"What an ad rule checks, and where.","additionalProperties":false,"properties":{"each":{"type":"string","enum":["campaign","adset","ad"],"description":"The objects judged one by one."},"adAccounts":{"type":"array","minItems":1,"maxItems":1,"description":"The ad account to check. One per ad rule, and an edit cannot move it to another.","items":{"type":"object","required":["accountId","adAccountId"],"additionalProperties":false,"properties":{"accountId":{"type":"string","description":"The ads connection, from `GET /v1/accounts`."},"adAccountId":{"type":"string","maxLength":64,"description":"Platform ad account ID, from `GET /v1/ads/accounts`."}}}},"campaignIds":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string"},"description":"Only these platform campaigns or their ad sets and ads. Leave out to check the whole ad account."},"filters":{"type":"array","minItems":1,"maxItems":10,"description":"All must hold.","items":{"$ref":"#/components/schemas/AutomationAdFilter"}},"groups":{"type":"array","minItems":1,"maxItems":20,"description":"Judges campaigns together (campaign rules only): each group's numbers are summed and its rates computed on the totals, and a matching group acts on each of its campaigns.\n\nA group with no filters holds every campaign the rule checks. `reach` and `frequency` cannot be used with groups.\n","items":{"type":"object","required":["name","filters"],"additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":60,"description":"Unique within the rule."},"filters":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/AutomationAdFilter"}}}}}}},"AutomationPostSubjects":{"type":"object","required":["each","profileId"],"additionalProperties":false,"description":"The posts a scheduled automation checks.","properties":{"each":{"type":"string","const":"post"},"profileId":{"type":"string","description":"The profile whose posts are checked."},"accountIds":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string"},"description":"Only posts of these accounts. Each must be active on the profile."},"publishedWithin":{"type":"string","pattern":"^[0-9]{1,5}(m|h|d)$","default":"7d","example":"3d","description":"How far back posts are checked, by when they were published. Whole days, from `1d` to `30d` (`48h` is 2 days)."}}},"AutomationAlert":{"type":"object","additionalProperties":false,"description":"Turns matches into alerts: the ad rule acts only after `confirmChecks` matching checks in a row, keeps the alert open while `hold` holds and marks it critical when `critical` holds.","properties":{"confirmChecks":{"type":"integer","minimum":1,"maximum":5},"hold":{"$ref":"#/components/schemas/AdRuleConditions"},"critical":{"$ref":"#/components/schemas/AdRuleConditions"}}},"AutomationNotifyStep":{"type":"object","required":["type"],"additionalProperties":false,"description":"Sends a summary to Slack channels or email addresses of connected accounts. In an ad rule it also sends the `ad_rule.triggered` webhook, and `to` is optional.\n\nEvent and scheduled automations need `to`.\n","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$","description":"In an ad rule the id is always `notify`."},"type":{"type":"string","const":"notify.send"},"to":{"type":"array","minItems":1,"description":"Up to 5 in an ad rule.","items":{"type":"object","required":["accountId"],"additionalProperties":false,"description":"Send `to` or `channelId`, not both.","properties":{"accountId":{"type":"string"},"to":{"type":"string","format":"email","description":"An address for a connected Gmail or Outlook account."},"channelId":{"type":"string","description":"A channel of a connected Slack account."}}}}}},"AutomationApprovalStep":{"type":"object","required":["type","to","expiresIn"],"additionalProperties":false,"description":"Makes the ad rule wait for a person's OK before it acts. One per ad rule, placed before the change. Each change waits until one of `to` approves it, for `expiresIn` at most.\n","properties":{"id":{"type":"string","const":"approval"},"type":{"type":"string","const":"approval.request"},"to":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","format":"email"},"description":"Team members, by email. Each once."},"expiresIn":{"type":"string","pattern":"^[0-9]{1,5}(m|h|d)$","example":"1d","description":"From `15m` to `7d`, in whole minutes."}}},"AutomationStep":{"description":"One thing an ad rule does for each matching object, in order. An ad rule takes at most one `ads.*` change, can ask for approval before it and notify after it.\n\n`id` is fixed by the step type; leave it out when writing. `GET /v1/automations/catalog` lists the platforms and subjects each step works on.\n","oneOf":[{"type":"object","required":["type"],"additionalProperties":false,"properties":{"id":{"type":"string","const":"pause"},"type":{"type":"string","const":"ads.pause"}}},{"type":"object","required":["type"],"additionalProperties":false,"description":"Turns objects back on once their cooldown has passed.","properties":{"id":{"type":"string","const":"activate"},"type":{"type":"string","const":"ads.activate"},"includeManuallyPaused":{"type":"boolean","description":"Also objects a person paused. Without it only what this automation paused is turned back on."}}},{"type":"object","required":["type"],"additionalProperties":false,"properties":{"id":{"type":"string","const":"duplicate"},"type":{"type":"string","const":"ads.duplicate"},"status":{"type":"string","enum":["paused","active"],"description":"The copy starts paused unless `active`."},"renameSuffix":{"type":"string","minLength":1,"maxLength":50}}},{"type":"object","required":["type","by"],"additionalProperties":false,"description":"Changes the daily budget by a percent: an increase needs `max`, the budget it stops at, and a decrease needs `min`.","properties":{"id":{"type":"string","const":"budget"},"type":{"type":"string","const":"ads.change_budget"},"by":{"type":"string","pattern":"^[+-][0-9]{1,3}%$","example":"+20%","description":"Up to +100% or down to -90%."},"max":{"type":"number","exclusiveMinimum":0},"min":{"type":"number","exclusiveMinimum":0}}},{"type":"object","required":["type","amount"],"additionalProperties":false,"properties":{"id":{"type":"string","const":"budget"},"type":{"type":"string","const":"ads.set_budget"},"amount":{"type":"number","exclusiveMinimum":0,"description":"The daily budget to set, in the ad account currency."}}},{"type":"object","required":["type","by"],"additionalProperties":false,"description":"Changes a Meta ad set's bid cap or cost cap by a percent, bounded like a budget change. An ad set without one is skipped.","properties":{"id":{"type":"string","const":"bid"},"type":{"type":"string","const":"ads.change_bid"},"by":{"type":"string","pattern":"^[+-][0-9]{1,3}%$","example":"-10%","description":"Up to +100% or down to -90%."},"max":{"type":"number","exclusiveMinimum":0},"min":{"type":"number","exclusiveMinimum":0}}},{"type":"object","required":["type","amount"],"additionalProperties":false,"description":"Sets a Meta ad set's bid cap or cost cap, in the ad account currency.","properties":{"id":{"type":"string","const":"bid"},"type":{"type":"string","const":"ads.set_bid"},"amount":{"type":"number","exclusiveMinimum":0}}},{"type":"object","required":["type","target","by"],"additionalProperties":false,"description":"Changes a Google campaign's target CPA or target ROAS by a percent, bounded like a budget change.","properties":{"id":{"type":"string","const":"target"},"type":{"type":"string","const":"ads.change_target"},"target":{"type":"string","enum":["cpa","roas"]},"by":{"type":"string","pattern":"^[+-][0-9]{1,3}%$","example":"+10%"},"max":{"type":"number","exclusiveMinimum":0},"min":{"type":"number","exclusiveMinimum":0}}},{"type":"object","required":["type","target","amount"],"additionalProperties":false,"description":"Sets a Google campaign's target CPA (ad account currency) or target ROAS (a ratio, 3 is 300%).","properties":{"id":{"type":"string","const":"target"},"type":{"type":"string","const":"ads.set_target"},"target":{"type":"string","enum":["cpa","roas"]},"amount":{"type":"number","exclusiveMinimum":0}}},{"type":"object","required":["type","metric","window","from","to"],"additionalProperties":false,"description":"Moves daily budget from the matched objects ranked worst by `metric` over `window` to those ranked best. The total stays the same.\n\nSend `by` (a percent of each giver's budget) or `amount` (in all, split evenly), not both.\n","properties":{"id":{"type":"string","const":"reallocate"},"type":{"type":"string","const":"ads.reallocate_budget"},"metric":{"type":"string","example":"roas","description":"A condition metric or `result:<key>`, not a calendar metric."},"window":{"type":"string","example":"last_7d","description":"A condition window."},"best":{"type":"string","enum":["highest","lowest"],"description":"Which end is best. Defaults to lowest for `cpa`, `cpc`, `cpm`, `frequency` and cost results, highest otherwise."},"from":{"type":"integer","minimum":1,"maximum":10,"description":"How many objects give budget."},"to":{"type":"integer","minimum":1,"maximum":10,"description":"How many objects receive it."},"by":{"type":"string","pattern":"^[0-9]{1,3}%$","example":"20%","description":"From 1% to 90%."},"amount":{"type":"number","exclusiveMinimum":0},"min":{"type":"number","exclusiveMinimum":0,"description":"A giver's budget never goes below this."},"max":{"type":"number","exclusiveMinimum":0,"description":"A receiver's budget never goes above this."}}},{"type":"object","required":["type"],"additionalProperties":false,"description":"Tags the object's name: `add` puts text at the start (or the end), `remove` takes every copy of it out. Send one of them.","properties":{"id":{"type":"string","const":"edit_name"},"type":{"type":"string","const":"ads.edit_name"},"add":{"type":"string","minLength":1,"maxLength":50},"remove":{"type":"string","minLength":1,"maxLength":50},"at":{"type":"string","enum":["start","end"]}}},{"$ref":"#/components/schemas/AutomationApprovalStep"},{"$ref":"#/components/schemas/AutomationNotifyStep"}]},"AutomationBoostStep":{"type":"object","required":["type","adAccountId","budget","days","countries"],"additionalProperties":false,"description":"Promotes each matched Facebook or Instagram post once, as a Meta ad with a lifetime budget. Posts on other platforms are not boosted. It needs the Ads add-on.\n\nOne boost step per automation, and `limits.maxChangesPerDay` (up to 20) is required: the most posts boosted in a day. At most 5 posts are boosted per check.\n","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"type":{"type":"string","const":"ads.boost_post"},"adAccountId":{"type":"string","maxLength":64,"description":"The Meta ad account that pays, from `GET /v1/ads/accounts`."},"budget":{"type":"number","exclusiveMinimum":0,"description":"The whole spend of one boost, in the ad account currency."},"days":{"type":"integer","minimum":1,"maximum":30,"description":"How long each boost runs."},"goal":{"type":"string","enum":["engagement","awareness","video_views"],"default":"engagement"},"countries":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string","pattern":"^[A-Z]{2}$"},"example":["US","CA"],"description":"ISO 3166 alpha-2 codes."}}},"AutomationLimits":{"type":"object","additionalProperties":false,"description":"An ad rule's limits.","properties":{"cooldown":{"type":"string","pattern":"^[0-9]{1,5}(m|h|d)$","default":"1d","example":"3d","description":"How long an object is left alone after the rule acts on it. Whole minutes, up to `30d`."},"maxChangesPerDay":{"type":"integer","minimum":1,"maximum":100,"description":"Most changes across the last 24 hours. Needs an `ads.*` step."},"maxChangesPerObject":{"type":"integer","minimum":1,"maximum":100,"description":"Most times the rule may change one object, over its whole history. Needs an `ads.*` step."}}},"AutomationEventLimits":{"type":"object","additionalProperties":false,"description":"The limits of an event or scheduled automation.","properties":{"cooldown":{"type":"string","pattern":"^[0-9]{1,5}(s|m|h|d)$","example":"1h","description":"How long the same post or account is left alone after the automation acts on it, rounded up to whole minutes. None by default."},"maxChangesPerDay":{"type":"integer","minimum":1,"description":"Most runs across the last 24 hours. Required, up to 20, with a boost step."}}},"AdRuleAutomationDefinition":{"type":"object","required":["name","trigger","subjects","conditions","steps"],"description":"An ad rule. It is also readable under `/v1/ads/rules` with the same id. Unknown fields are refused.\n\nTo have a person OK each change before it is made, put an `approval.request` step before the `ads.*` step.\n","example":{"name":"Cut budget on losers, with approval","trigger":{"type":"schedule","every":"6h","quietHours":{"from":"22:00","to":"07:00"}},"subjects":{"each":"adset","adAccounts":[{"accountId":"6731a0c2e4b0f1a2b3c4d5e6","adAccountId":"act_1234567890"}]},"conditions":{"all":[{"metric":"cpa","window":"last_3d","op":">","value":40}]},"steps":[{"type":"approval.request","to":["lead@example.com"],"expiresIn":"1d"},{"type":"ads.change_budget","by":"-20%","min":10},{"type":"notify.send"}],"limits":{"cooldown":"1d","maxChangesPerDay":10}},"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"status":{"type":"string","enum":["active","paused"],"default":"paused","description":"A new ad rule stays paused unless `active`."},"trigger":{"$ref":"#/components/schemas/AutomationScheduleTrigger"},"subjects":{"$ref":"#/components/schemas/AutomationSubjects"},"conditions":{"$ref":"#/components/schemas/AdRuleConditions"},"alert":{"$ref":"#/components/schemas/AutomationAlert"},"steps":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/AutomationStep"}},"limits":{"$ref":"#/components/schemas/AutomationLimits"}}},"EventAutomationDefinition":{"type":"object","required":["name","trigger","steps"],"description":"Runs when something happens in Zernio, such as a post failing, and notifies. Unknown fields are refused.","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"status":{"type":"string","enum":["active","paused"],"default":"active","description":"A new event automation is on unless `paused`."},"trigger":{"$ref":"#/components/schemas/AutomationEventTrigger"},"steps":{"type":"array","minItems":1,"maxItems":10,"items":{"$ref":"#/components/schemas/AutomationNotifyStep"}},"limits":{"$ref":"#/components/schemas/AutomationEventLimits"}}},"ScheduledAutomationDefinition":{"type":"object","required":["name","trigger","subjects","steps"],"description":"Checks a profile's recent posts on a schedule. Each post that matches `filter` is notified about, and can be boosted. At most 20 posts are acted on per check. Unknown fields are refused.\n","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"status":{"type":"string","enum":["active","paused"],"default":"active","description":"A new scheduled automation is on unless `paused`."},"trigger":{"$ref":"#/components/schemas/AutomationPostSchedule"},"subjects":{"$ref":"#/components/schemas/AutomationPostSubjects"},"filter":{"$ref":"#/components/schemas/AutomationFactCondition"},"steps":{"type":"array","minItems":1,"maxItems":10,"items":{"oneOf":[{"$ref":"#/components/schemas/AutomationNotifyStep"},{"$ref":"#/components/schemas/AutomationBoostStep"}]}},"limits":{"$ref":"#/components/schemas/AutomationEventLimits"}}},"AutomationDefinition":{"description":"An automation of one of three kinds, told apart by its shape:\n\n- **Ad rule**: a `schedule` trigger over campaigns, ad sets or ads, with metric `conditions` and ad `steps`.\n- **Event**: a Zernio event in `trigger.type`, narrowed by `trigger.filter`, with notify steps.\n- **Scheduled**: a `schedule` trigger over `subjects.each: post`, narrowed by `filter`, with notify and boost steps.\n","oneOf":[{"$ref":"#/components/schemas/AdRuleAutomationDefinition"},{"$ref":"#/components/schemas/EventAutomationDefinition"},{"$ref":"#/components/schemas/ScheduledAutomationDefinition"}]},"AutomationRecord":{"type":"object","required":["id","kind","status","version","lastCheckAt","nextCheckAt","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["ad_rule","event","scheduled"]},"status":{"type":"string","enum":["active","paused"]},"version":{"type":"string","description":"Send it back as `If-Match` when editing, so an edit made after someone else saved is refused."},"lastCheckAt":{"type":["string","null"],"format":"date-time","description":"Null until an ad rule first checks. Always null for event and scheduled automations; their checks list when they ran."},"nextCheckAt":{"type":["string","null"],"format":"date-time","description":"Null while paused. Always null for event and scheduled automations."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"template":{"type":"object","required":["id","name","version","latestVersion"],"description":"Only on `GET /v1/automations/{automationId}`, for an automation installed from a template.","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"version":{"type":"integer","description":"The template version it was installed from."},"latestVersion":{"type":["integer","null"],"description":"Null once the template is deleted."}}}}},"Automation":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/AdRuleAutomationDefinition"},{"$ref":"#/components/schemas/AutomationRecord"},{"type":"object","required":["limits"],"properties":{"kind":{"type":"string","const":"ad_rule"}}}]},{"allOf":[{"$ref":"#/components/schemas/EventAutomationDefinition"},{"$ref":"#/components/schemas/AutomationRecord"},{"type":"object","required":["limits"],"properties":{"kind":{"type":"string","const":"event"}}}]},{"allOf":[{"$ref":"#/components/schemas/ScheduledAutomationDefinition"},{"$ref":"#/components/schemas/AutomationRecord"},{"type":"object","required":["limits"],"properties":{"kind":{"type":"string","const":"scheduled"}}}]}]},"AutomationProblems":{"type":"object","description":"Every problem with the automation, each at a JSON path such as `steps[0].by`. The first one also fills `error` and `param`.","properties":{"problems":{"type":"array","items":{"type":"object","required":["path","code","message"],"properties":{"path":{"type":"string","example":"trigger.every"},"code":{"type":"string","enum":["invalid_value","not_supported"]},"message":{"type":"string"}}}}}},"AutomationActionResult":{"type":"object","required":["step","type","status","reason","previous","target"],"description":"What an ad rule did to one object, as an absolute change: a budget change reads as the budget it set.","properties":{"step":{"type":"string","description":"The id of the step that made it, for example `budget`."},"type":{"type":"string","enum":["ads.pause","ads.activate","ads.set_budget","ads.duplicate","ads.edit_name","ads.set_bid","ads.set_target","ads.reallocate_budget"]},"status":{"type":"string","enum":["applied","skipped","failed"]},"reason":{"type":["string","null"],"description":"Why it was skipped or failed, such as `already_paused`, `daily_limit_reached` or `awaiting_approval`."},"previous":{"$ref":"#/components/schemas/AutomationChangedValue"},"target":{"$ref":"#/components/schemas/AutomationChangedValue"}}},"AutomationChangedValue":{"type":["object","null"],"description":"The one value the change moved, keyed by what it is. Null when it moved none, as for a pause.","properties":{"dailyBudget":{"type":"number"},"name":{"type":"string"},"bidAmount":{"type":"number"},"targetCpa":{"type":"number"},"targetRoas":{"type":"number"}}},"AdRuleAutomationCheck":{"type":"object","required":["id","automationId","checkedAt","outcome","evaluated","subjects","actions","notification","error"],"description":"One check of an ad rule.","properties":{"id":{"type":"string"},"automationId":{"type":"string"},"checkedAt":{"type":"string","format":"date-time"},"outcome":{"type":"string","enum":["triggered","cooldown","no_match","failed"]},"evaluated":{"type":"integer","description":"Objects judged."},"subjects":{"type":"array","items":{"type":"object","properties":{"subject":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"campaignId":{"type":["string","null"]}}},"matched":{"type":"boolean"},"conditions":{"type":"array","items":{"type":"object"}}}}},"actions":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AutomationActionResult"},{"type":"object","properties":{"subjectId":{"type":"string"}}}]}},"notification":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["done","failed"]},"reason":{"type":"string"}}},"error":{"type":["string","null"]}}},"AutomationFactResult":{"type":"object","description":"One leaf of the filter, with the fact's value at the check. Content facts are null for teams that keep no content.","properties":{"field":{"type":"string"},"op":{"type":"string"},"value":{},"actual":{},"met":{"type":"boolean"}}},"AutomationRunResult":{"type":"object","required":["type","status","reason"],"properties":{"type":{"type":"string","enum":["notify.send","ads.boost_post"]},"status":{"type":"string","enum":["pending","applied","skipped","failed","unknown"],"description":"`unknown` when the platform never answered, so the outcome is not known."},"reason":{"type":["string","null"]}}},"EventAutomationCheck":{"type":"object","required":["id","automationId","checkedAt","outcome","evaluated","event","eventId","subject","filter","actions","error"],"description":"One event that reached an event automation.","properties":{"id":{"type":"string"},"automationId":{"type":"string"},"checkedAt":{"type":"string","format":"date-time"},"outcome":{"type":"string","enum":["triggered","no_match","cooldown","daily_limit","failed"]},"evaluated":{"type":"integer"},"event":{"type":["string","null"],"example":"post.failed"},"eventId":{"type":["string","null"]},"subject":{"type":["object","null"],"description":"What the event was about.","properties":{"kind":{"type":"string","example":"post"},"id":{"type":"string"},"accountId":{"type":"string"}}},"filter":{"type":"array","items":{"$ref":"#/components/schemas/AutomationFactResult"}},"actions":{"type":"array","items":{"$ref":"#/components/schemas/AutomationRunResult"}},"error":{"type":["string","null"]}}},"ScheduledAutomationCheck":{"type":"object","required":["id","automationId","checkedAt","outcome","evaluated","analyticsSyncedAt","matched","actions","error"],"description":"One check of a scheduled automation.","properties":{"id":{"type":"string"},"automationId":{"type":"string"},"checkedAt":{"type":"string","format":"date-time"},"outcome":{"type":"string","enum":["triggered","no_match","cooldown","daily_limit","failed"]},"evaluated":{"type":"integer","description":"Posts judged."},"analyticsSyncedAt":{"type":["string","null"],"format":"date-time","description":"The oldest analytics sync among the posts judged: their numbers are as of then."},"matched":{"type":"array","description":"Up to 20 matching posts.","items":{"type":"object","properties":{"postId":{"type":"string"},"accountId":{"type":"string"},"platform":{"type":"string"},"url":{"type":["string","null"]},"filter":{"type":"array","items":{"$ref":"#/components/schemas/AutomationFactResult"}}}}},"actions":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AutomationRunResult"},{"type":"object","properties":{"postId":{"type":"string"}}}]}},"error":{"type":["string","null"]}}},"AutomationCheck":{"description":"One check, shaped by the automation's kind.","oneOf":[{"$ref":"#/components/schemas/AdRuleAutomationCheck"},{"$ref":"#/components/schemas/EventAutomationCheck"},{"$ref":"#/components/schemas/ScheduledAutomationCheck"}]},"AutomationAction":{"allOf":[{"$ref":"#/components/schemas/AutomationActionResult"},{"type":"object","required":["id","automationId","automationName","checkId","subject","platform","adAccount","currency","createdAt"],"properties":{"id":{"type":"string"},"automationId":{"type":"string"},"automationName":{"type":"string"},"checkId":{"type":"string"},"subject":{"type":"object","properties":{"kind":{"type":"string","enum":["campaign","adset","ad"]},"id":{"type":"string"},"name":{"type":["string","null"]}}},"platform":{"type":"string"},"adAccount":{"type":"object","properties":{"accountId":{"type":"string"},"adAccountId":{"type":"string"}}},"currency":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}}]},"AutomationConditionResult":{"type":"object","properties":{"path":{"type":"string","example":"conditions.all[0]"},"metric":{"type":"string"},"window":{"type":"string"},"op":{"type":"string"},"value":{"type":"number"},"compareTo":{"type":"string"},"actual":{"type":["number","null"],"description":"Null when the value is unknown; such a condition never holds."},"met":{"type":"boolean"}}},"AutomationPreview":{"type":"object","required":["evaluatedAt","today","timezone","timezoneAssumed","currency","evaluated","matched","truncated","subjects"],"description":"What an ad rule would do if it ran now. Nothing is changed. Cooldowns and daily caps are left out, so a run right after can act on fewer objects.\n","properties":{"evaluatedAt":{"type":"string","format":"date-time"},"today":{"type":"string","format":"date","description":"Today in the ad account timezone."},"timezone":{"type":"string"},"timezoneAssumed":{"type":"boolean","description":"True when the ad account timezone is unknown and UTC was used."},"currency":{"type":["string","null"]},"evaluated":{"type":"integer"},"matched":{"type":"integer"},"truncated":{"type":"boolean","description":"True when more subjects were judged than `limit` lists."},"subjects":{"type":"array","description":"Matches first, up to `limit`.","items":{"type":"object","required":["subject","matched","conditions","wouldRun"],"properties":{"subject":{"type":"object","properties":{"kind":{"type":"string","enum":["campaign","adset","ad"]},"id":{"type":"string","description":"Platform ID."},"name":{"type":"string"},"campaignId":{"type":["string","null"]}}},"group":{"type":"string","description":"The group it was judged in, when the rule has `subjects.groups`."},"matched":{"type":"boolean"},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/AutomationConditionResult"}},"wouldRun":{"type":"array","items":{"type":"object","properties":{"step":{"type":"string"},"type":{"type":"string"}}}}}}},"groups":{"type":"array","description":"Each group's totals against the conditions, when the rule has `subjects.groups`.","items":{"type":"object","properties":{"name":{"type":"string"},"matched":{"type":"boolean"},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/AutomationConditionResult"}},"campaignIds":{"type":"array","items":{"type":"string"}}}}}}},"AutomationTemplateInput":{"type":"object","description":"Something an install asks for. Each automation in the template holds `{ \"$input\": \"<key>\" }` where the value goes, and installing puts the value sent in `inputs.<key>` there.","required":["key","type","label"],"properties":{"key":{"type":"string","description":"The name to send the value under in `inputs`, for example `adAccount`.","example":"adAccount"},"type":{"type":"string","enum":["ad_account","profile","social_accounts","notify_destination","number","money","percent","choice"],"description":"What the value is. `ad_account`: `{ accountId, adAccountId }`. `profile`: a profile id. `social_accounts`: an array of social account ids. `notify_destination`: an array of `{ accountId, to?, channelId? }`. `number`, `money` (in the ad account's currency) and `percent`: a number within the bounds below. `choice`: one of `options[].value`."},"label":{"type":"string","example":"Ad account"},"optional":{"type":"boolean","description":"True when an install may leave it out. A field that points at a left-out input is dropped."},"default":{"type":["string","number"],"description":"Used when an install leaves the input out. An input with a default is never missing."},"min":{"type":"number"},"exclusiveMin":{"type":"number","description":"The value must be above it, for example an amount above 0."},"max":{"type":"number"},"integer":{"type":"boolean","description":"True when only whole numbers are accepted."},"options":{"type":"array","description":"What a `choice` input offers.","items":{"type":"object","required":["value","label"],"properties":{"value":{"type":["string","number"]},"label":{"type":"string"}}}}}},"AutomationTemplateAutomation":{"type":"object","required":["key","definition"],"properties":{"key":{"type":"string","description":"Stable within the template, for example `automation1`.","example":"automation1"},"definition":{"type":"object","additionalProperties":true,"description":"A `POST /v1/automations` body without `status`, in which every value tied to one account is an input reference such as `{ \"$input\": \"adAccount\" }`. Campaign ids, id filters, start and end dates and approval steps are not kept."}}},"AutomationTemplate":{"type":"object","required":["id","name","description","publisher","visibility","version","areas","inputs","automations","installs","share"],"properties":{"id":{"type":"string","description":"A team template's id (24 hex characters), or the id of one of Zernio's templates such as `stop_losers`."},"name":{"type":"string"},"description":{"type":"string"},"publisher":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["team","zernio"],"description":"`team` for your team's templates and shared ones, `zernio` for Zernio's own."}}},"visibility":{"type":"string","enum":["team","link","public"],"description":"`team`: your team only. `link`: anyone with the share link can read and install it. `public`: one of Zernio's templates."},"version":{"type":"integer","minimum":1,"description":"Goes up each time the content changes. Renaming or sharing keeps it."},"areas":{"type":"array","items":{"type":"string","enum":["ads","events","posts","inbox","comments"]},"description":"What its automations work on."},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/AutomationTemplateInput"}},"automations":{"type":"array","items":{"$ref":"#/components/schemas/AutomationTemplateAutomation"}},"installs":{"type":"integer","description":"Installs across every team. Always 0 on Zernio's templates."},"installedInTeam":{"type":"integer","description":"Your team's automations made from it. Absent on shared and Zernio templates."},"share":{"type":["object","null"],"description":"While shared by link (on your own templates only). Null otherwise.","required":["token","path"],"properties":{"token":{"type":"string","description":"The share token for `/v1/automations/templates/shared/{shareToken}`."},"path":{"type":"string","description":"The dashboard page that opens the template."}}},"createdBy":{"type":"string","description":"The user who saved it. Only on your team's templates."},"createdAt":{"type":"string","format":"date-time","description":"Absent on Zernio's templates."},"updatedAt":{"type":"string","format":"date-time","description":"Absent on Zernio's templates."}}},"AutomationTemplateContent":{"type":"object","description":"Where the automations come from. Send `from` or `automations`, not both.","properties":{"from":{"description":"Copy existing automations: your own (`automationIds`), one of Zernio's templates (`templateId`, for example `stop_losers`), or a template shared by link (`shareToken`).","oneOf":[{"type":"object","title":"From your automations","required":["automationIds"],"additionalProperties":false,"properties":{"automationIds":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","pattern":"^[0-9a-f]{24}$"}}}},{"type":"object","title":"From a Zernio template","required":["templateId"],"additionalProperties":false,"properties":{"templateId":{"type":"string","minLength":1,"maxLength":64}}},{"type":"object","title":"From a shared template","required":["shareToken"],"additionalProperties":false,"properties":{"shareToken":{"type":"string","minLength":1,"maxLength":64}}}]},"automations":{"type":"array","minItems":1,"maxItems":20,"description":"Automation definitions, each checked like a `POST /v1/automations` body. Ad accounts, a trigger's profile and accounts, and alert destinations become inputs.","items":{"$ref":"#/components/schemas/AutomationDefinition"}}}},"AutomationTemplateInstallRequest":{"type":"object","additionalProperties":false,"properties":{"inputs":{"type":"object","additionalProperties":true,"default":{},"description":"A value for each input, by its `key`. Required inputs without a default must be sent.","example":{"adAccount":{"accountId":"6731a0c2e4b0f1a2b3c4d5e6","adAccountId":"act_1234567890"}}},"targets":{"type":"array","minItems":1,"maxItems":50,"description":"Install several times in one call, for example on many ad accounts. Each target is its own install, all or nothing, and its `inputs` win over the shared `inputs`. A failed target leaves the others in place.","items":{"type":"object","required":["inputs"],"additionalProperties":false,"properties":{"inputs":{"type":"object","additionalProperties":true}}}},"status":{"type":"string","enum":["active","paused"],"default":"paused","description":"The status of every automation created."}}},"AutomationTemplateInstallation":{"type":"object","required":["templateId","templateVersion","automations"],"properties":{"templateId":{"type":"string"},"templateVersion":{"type":"integer"},"automations":{"type":"array","items":{"$ref":"#/components/schemas/Automation"}}}},"AutomationTemplateTargetResult":{"type":"object","required":["target","status"],"properties":{"target":{"type":"integer","description":"The index of the entry in `targets`."},"status":{"type":"string","enum":["created","failed"]},"installation":{"$ref":"#/components/schemas/AutomationTemplateInstallation"},"error":{"type":"object","description":"Why this target did not install. Problem paths point into the request, such as `targets[2].inputs.adAccount`.","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}},"AutomationTemplateInstallResponse":{"oneOf":[{"type":"object","title":"One install","required":["installation"],"properties":{"installation":{"$ref":"#/components/schemas/AutomationTemplateInstallation"}}},{"type":"object","title":"Several targets","required":["installations"],"properties":{"installations":{"type":"array","description":"One result per target, in order.","items":{"$ref":"#/components/schemas/AutomationTemplateTargetResult"}}}}]},"AutomationControls":{"type":"object","required":["paused","pausedAt","adAccounts"],"description":"The team's switch for every ad rule, and each ad account's own controls. Every team member sees the same ones.","properties":{"paused":{"type":"boolean","description":"True when every ad rule of the team is stopped. Each rule keeps its own status."},"pausedAt":{"type":["string","null"],"format":"date-time","description":"When the team switch was turned off; null while it is on."},"adAccounts":{"type":"array","description":"Every ad account your automations use, plus any ad account that has controls set.","items":{"$ref":"#/components/schemas/AutomationAdAccountControls"}}}},"AutomationAdAccountControls":{"type":"object","required":["accountId","platform","adAccountId","paused","pausedAt","dailyRaiseLimit"],"properties":{"accountId":{"type":["string","null"],"description":"The connection your automations reach the ad account through; null when no automation uses it any more."},"platform":{"type":"string","description":"The ad platform, for example `facebook`."},"adAccountId":{"type":"string","description":"The platform's ad account id."},"paused":{"type":"boolean","description":"True when every ad rule on this ad account is stopped."},"pausedAt":{"type":["string","null"],"format":"date-time"},"dailyRaiseLimit":{"type":["number","null"],"description":"The most automations may raise budgets on this ad account in any 24 hours, in the ad account's currency. Null when there is no limit."}}},"AutomationApprovalDecision":{"type":"object","additionalProperties":false,"properties":{"token":{"type":"string","minLength":1,"maxLength":200,"description":"The token from the emailed approval link. When sent, the decision counts only if the link was sent to you. Leave it out when deciding from the API."}}},"AutomationApproval":{"type":"object","required":["id","automationId","checkId","status","to","expiresAt","createdAt","decidedBy","decidedAt","canDecide","changes"],"description":"A request an automation sent for a person's approval before acting, with each change it holds.","properties":{"id":{"type":"string"},"automationId":{"type":"string"},"checkId":{"type":"string","description":"The check that found the matches and sent the request."},"status":{"type":"string","enum":["pending","approved","rejected","expired","cancelled"],"description":"`cancelled` when the automation stopped asking for approval before anyone decided."},"to":{"type":"array","items":{"type":"string","format":"email"},"description":"The emails the request was sent to."},"expiresAt":{"type":"string","format":"date-time","description":"After this the request can no longer be decided and its changes are skipped."},"createdAt":{"type":"string","format":"date-time"},"decidedBy":{"type":["object","null"],"properties":{"email":{"type":"string","format":"email"}},"description":"Who approved or rejected it; null while undecided."},"decidedAt":{"type":["string","null"],"format":"date-time"},"canDecide":{"type":"boolean","description":"True when the request is pending and you are one of the approvers the automation names now."},"changes":{"type":"array","description":"The changes the request holds. Notifications are not listed.","items":{"$ref":"#/components/schemas/AutomationApprovalChange"}}}},"AutomationApprovalChange":{"type":"object","required":["actionId","subject","type","previous","target","conditions","status","reason"],"properties":{"actionId":{"type":"string"},"subject":{"type":"object","required":["kind","id","name"],"properties":{"kind":{"type":"string","enum":["campaign","adset","ad"]},"id":{"type":"string"},"name":{"type":["string","null"]}}},"type":{"type":"string","enum":["ads.pause","ads.activate","ads.set_budget","ads.duplicate","ads.edit_name","ads.set_bid","ads.set_target","ads.reallocate_budget"]},"previous":{"type":["object","null"],"description":"The value before the change, under one of `dailyBudget`, `name`, `bidAmount`, `targetCpa` or `targetRoas`. Null when the change moves no value.","properties":{"dailyBudget":{"type":"number"},"name":{"type":"string"},"bidAmount":{"type":"number"},"targetCpa":{"type":"number"},"targetRoas":{"type":"number"}}},"target":{"type":["object","null"],"description":"The value the change sets, keyed like `previous`.","properties":{"dailyBudget":{"type":"number"},"name":{"type":"string"},"bidAmount":{"type":"number"},"targetCpa":{"type":"number"},"targetRoas":{"type":"number"}}},"conditions":{"type":"array","items":{"type":"object"},"description":"Each condition as it was judged when the request was sent, with its actual value."},"status":{"type":"string","enum":["pending","applied","skipped","failed","unknown"],"description":"`pending` until the request is decided."},"reason":{"type":["string","null"],"description":"Why the change was made, skipped or failed, when known."}}},"AutomationBacktest":{"type":"object","required":["from","to","timezone","timezoneAssumed","currency","totals","days","notes"],"description":"What the automation would have done on each past day, replayed on stored daily metrics. Nothing is changed.","properties":{"from":{"type":"string","format":"date","description":"The first day replayed, in the ad account timezone."},"to":{"type":"string","format":"date","description":"The last day replayed, yesterday in the ad account timezone."},"timezone":{"type":"string"},"timezoneAssumed":{"type":"boolean","description":"True when the ad account timezone is unknown and UTC was used."},"currency":{"type":["string","null"]},"totals":{"type":"object","required":["actions","pauses","activations","budgetRaised","budgetLowered","budgetChange","notifications","skipped","subjects","heldBack","daysWithActions"],"properties":{"actions":{"type":"integer","description":"Actions it would have taken. Skipped ones are not counted."},"pauses":{"type":"integer"},"activations":{"type":"integer"},"budgetRaised":{"type":"integer","description":"Budget changes that raised a budget."},"budgetLowered":{"type":"integer","description":"Budget changes that lowered a budget."},"budgetChange":{"type":"number","description":"The net budget change across every budget action, in `currency`."},"notifications":{"type":"integer"},"skipped":{"type":"integer","description":"Actions planned but skipped."},"subjects":{"type":"integer","description":"Distinct objects it would have acted on."},"heldBack":{"type":"integer","description":"Matches left alone by the cooldown or a cap, summed over the days."},"daysWithActions":{"type":"integer"}}},"days":{"type":"array","items":{"$ref":"#/components/schemas/AutomationBacktestDay"}},"notes":{"type":"array","description":"What this replay could not know, for example that budgets have no history.","items":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["budget_assumed","results_not_replayed","reach_stored","today_whole_day","pause_history","status_history","no_checks","same_day_numbers","alerts_not_replayed"]},"message":{"type":"string"}}}}}},"AutomationBacktestDay":{"type":"object","required":["date","checks","evaluated","matched","heldBack","actions"],"properties":{"date":{"type":"string","format":"date"},"checks":{"type":"integer","description":"Checks the schedule would have run that day. 0 on a day it skips."},"evaluated":{"type":"integer","description":"The most objects any of the day's checks judged."},"matched":{"type":"integer","description":"The most objects any of the day's checks matched."},"heldBack":{"type":"integer","description":"Matches left alone all day by the cooldown or a cap."},"actions":{"type":"array","items":{"type":"object","required":["subject","type"],"properties":{"subject":{"type":"object","required":["kind","id","name","campaignId"],"properties":{"kind":{"type":"string","enum":["campaign","adset","ad"]},"id":{"type":"string"},"name":{"type":"string"},"campaignId":{"type":["string","null"]}}},"group":{"type":"string","description":"For an automation with groups, the group the campaign was judged in."},"type":{"type":"string","enum":["ads.pause","ads.activate","ads.set_budget","ads.duplicate","ads.edit_name","ads.set_bid","ads.set_target","ads.reallocate_budget","notify.send"]},"budget":{"type":"object","description":"For a budget change, the daily budget before and after.","required":["from","to"],"properties":{"from":{"type":"number"},"to":{"type":"number"}}},"skipped":{"type":"string","enum":["budget_unknown","at_limit","already_at_amount"],"description":"Why it would have been skipped. Absent when it would have acted."}}}}}},"AdRule":{"type":"object","required":["id","name","accountId","platform","adAccountId","level","campaignIds","filters","groups","lifecycle","conditions","actions","schedule","cooldownMinutes","enabled","lastRunAt","nextRunAt","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"accountId":{"type":"string","description":"The ads connection the rule acts through."},"platform":{"type":"string","description":"Ad platform, for example `facebook` (Meta) or `google`."},"adAccountId":{"type":"string","description":"Platform ad account ID."},"level":{"$ref":"#/components/schemas/AdRuleLevel"},"campaignIds":{"type":["array","null"],"items":{"type":"string"},"description":"Platform campaign IDs the rule is limited to. Null checks the whole ad account."},"filters":{"$ref":"#/components/schemas/AdRuleFilters"},"groups":{"$ref":"#/components/schemas/AdRuleGroups"},"lifecycle":{"oneOf":[{"$ref":"#/components/schemas/AdRuleLifecycle"},{"type":"null"}],"description":"Null when every matching run acts and notifies."},"conditions":{"$ref":"#/components/schemas/AdRuleConditions"},"actions":{"$ref":"#/components/schemas/AdRuleActions"},"schedule":{"$ref":"#/components/schemas/AdRuleSchedule"},"cooldownMinutes":{"type":"integer"},"enabled":{"type":"boolean"},"lastRunAt":{"type":["string","null"],"format":"date-time"},"nextRunAt":{"type":["string","null"],"format":"date-time","description":"Null while the rule is disabled."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"AdRuleObjectEvaluation":{"type":"object","required":["id","name","campaignId","matched","conditions"],"properties":{"id":{"type":"string","description":"Platform ID of the campaign or ad set."},"name":{"type":"string"},"campaignId":{"type":["string","null"]},"matched":{"type":"boolean","description":"True when every condition holds."},"group":{"type":"string","description":"For a rule with groups: the group this campaign was judged in. `matched` and `conditions` are the group's."},"conditions":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AdRuleCondition"},{"type":"object","required":["actual","met"],"properties":{"actual":{"type":["number","null"],"description":"The object's value over the window. Null when it cannot be computed."},"met":{"type":"boolean"}}}]}}}},"AdRuleEvaluation":{"type":"object","required":["evaluatedAt","today","timezone","timezoneAssumed","currency","matched","objects"],"properties":{"evaluatedAt":{"type":"string","format":"date-time"},"today":{"type":"string","format":"date","description":"The ad account's calendar date the windows were resolved against."},"timezone":{"type":"string","description":"IANA timezone of the ad account."},"timezoneAssumed":{"type":"boolean","description":"True when the ad account has no known timezone and UTC was assumed."},"currency":{"type":["string","null"]},"matched":{"type":"integer","description":"How many objects meet every condition."},"objects":{"type":"array","description":"Every delivering campaign or ad set in scope (for an `activate` rule, the rule-paused ones it may reactivate).","items":{"$ref":"#/components/schemas/AdRuleObjectEvaluation"}},"groups":{"type":["array","null"],"description":"Each group's totals, for a rule with groups. Null otherwise.","items":{"type":"object","required":["name","matched","conditions","campaignIds"],"properties":{"name":{"type":"string"},"matched":{"type":"boolean"},"conditions":{"type":"array","items":{"type":"object"},"description":"Like an object's conditions, read on the group's totals."},"campaignIds":{"type":"array","items":{"type":"string"},"description":"Every campaign counted in the group, paused ones included."}}}}}},"AdRuleRun":{"type":"object","required":["id","ranAt","outcome","objectsEvaluated","actedObjectIds","evaluation","error"],"properties":{"id":{"type":"string"},"ranAt":{"type":"string","format":"date-time"},"outcome":{"type":"string","enum":["triggered","cooldown","no_match","failed"],"description":"Result of the rule run:\n\n- `triggered`: the rule acted on at least one object (`error` is set if the webhook could not be sent afterwards).\n- `cooldown`: objects matched but all were in cooldown.\n- `no_match`: nothing matched.\n- `failed`: the metrics could not be read, every action failed, or the webhook of a notify-only rule could not be sent (see `error`).\n"},"objectsEvaluated":{"type":"integer"},"actedObjectIds":{"type":"array","items":{"type":"string"}},"evaluation":{"type":["object","null"],"description":"The matched objects with their condition values, and what each action did.","properties":{"rule":{"type":"object","description":"The rule as it was when this run happened, so its actions stay readable after the rule is renamed or deleted. Absent on runs recorded before October 2026.","properties":{"name":{"type":"string"},"profileId":{"type":"string"},"accountId":{"type":"string"},"platform":{"type":"string"},"platformAdAccountId":{"type":"string"},"level":{"type":"string","enum":["campaign","adset"]}}},"today":{"type":"string","format":"date"},"timezone":{"type":"string"},"timezoneAssumed":{"type":"boolean"},"currency":{"type":["string","null"]},"matched":{"type":"array","items":{"$ref":"#/components/schemas/AdRuleObjectEvaluation"}},"actions":{"type":"array","items":{"type":"object","required":["objectId","type","status"],"properties":{"objectId":{"type":"string"},"type":{"type":"string","enum":["pause","activate","adjust_budget","adjust_bid","adjust_target","reallocate_budget","duplicate","edit_name"]},"status":{"type":"string","enum":["done","skipped","failed"]},"reason":{"type":"string","description":"Why it was skipped or failed, for example `already_paused`."},"previousDailyBudget":{"type":"number"},"newDailyBudget":{"type":"number"},"previousName":{"type":"string"},"newName":{"type":"string"},"previousBidAmount":{"type":"number"},"newBidAmount":{"type":"number"},"targetMetric":{"type":"string","enum":["cpa","roas"]},"previousTarget":{"type":"number"},"newTarget":{"type":"number"}}}},"notification":{"type":"object","description":"Set when a run of a rule with a `notify` action matched objects and tried to send the webhook. A notify-only rule whose webhook fails ends with outcome `failed`.\n\n- `done`: the `ad_rule.triggered` webhook is queued for the webhooks subscribed to it (with none subscribed it is still `done`, but nothing is delivered).\n- `failed`: it could not be queued.\n","required":["status"],"properties":{"status":{"type":"string","enum":["done","failed"]},"reason":{"type":"string","description":"Why the webhook could not be queued."}}}}},"error":{"type":["string","null"]}}},"AdRuleActivityEntry":{"type":"object","required":["id","ranAt","ruleId","ruleName","platform","accountId","adAccountId","level","objectId","objectName","type","status","reason","previousDailyBudget","newDailyBudget","previousName","newName","previousBidAmount","newBidAmount","targetMetric","previousTarget","newTarget","currency"],"properties":{"id":{"type":"string","description":"Stable ID of this entry."},"ranAt":{"type":"string","format":"date-time"},"ruleId":{"type":"string"},"ruleName":{"type":"string","description":"The rule's name when it acted."},"platform":{"type":"string"},"accountId":{"type":"string","description":"The ads connection the rule runs on."},"adAccountId":{"type":"string"},"level":{"type":"string","enum":["campaign","adset"]},"objectId":{"type":"string","description":"Platform ID of the campaign or ad set."},"objectName":{"type":["string","null"],"description":"Its name when the rule acted."},"type":{"type":"string","enum":["pause","activate","adjust_budget","adjust_bid","adjust_target","reallocate_budget","duplicate","edit_name"]},"status":{"type":"string","enum":["done","skipped","failed"]},"reason":{"type":["string","null"],"description":"Why it was skipped or failed, for example `already_paused`."},"previousDailyBudget":{"type":["number","null"]},"newDailyBudget":{"type":["number","null"]},"previousName":{"type":["string","null"],"description":"The name before an `edit_name`."},"newName":{"type":["string","null"],"description":"The name an applied `edit_name` set."},"previousBidAmount":{"type":["number","null"],"description":"The bid cap or cost cap before an `adjust_bid`."},"newBidAmount":{"type":["number","null"],"description":"The cap an applied `adjust_bid` set."},"targetMetric":{"type":["string","null"],"enum":["cpa","roas",null],"description":"Which target an `adjust_target` moved."},"previousTarget":{"type":["number","null"],"description":"The target CPA or target ROAS before an `adjust_target`."},"newTarget":{"type":["number","null"],"description":"The target an applied `adjust_target` set."},"currency":{"type":["string","null"]}}},"AdKeyword":{"type":"object","properties":{"id":{"type":"string","description":"Zernio keyword ID. Accepted as `keywordId` by PATCH/DELETE /v1/ads/keywords/{keywordId}."},"platformCriterionId":{"type":"string","description":"Google ad_group_criterion.criterion_id. Unique only within its ad group (`adSetId`), not across the account."},"resourceName":{"type":"string","description":"Google resource name, customers/{adAccountId}/adGroupCriteria/{adSetId}~{platformCriterionId}."},"accountId":{"type":"string","description":"Account ID owning the sync"},"profileId":{"type":"string","description":"Profile the row belongs to: the profile of its owning connection (`accountId`); when that connection no longer exists, the requested profile (`profileId` filter) that reaches the row ad account, else the profile of the oldest connection of the row owner that reaches it."},"platform":{"type":"string","enum":["google"]},"adAccountId":{"type":"string","description":"Google customer ID"},"campaignId":{"type":"string"},"campaignName":{"type":["string","null"]},"campaignStatus":{"type":["string","null"]},"adSetId":{"type":"string","description":"Google ad group ID"},"adSetName":{"type":["string","null"]},"adSetStatus":{"type":["string","null"]},"keyword":{"type":"string"},"matchType":{"type":"string","enum":["exact","phrase","broad","unknown"]},"status":{"type":"string","enum":["active","paused"]},"negative":{"type":"boolean"},"qualityScore":{"type":["integer","null"],"description":"Deprecated, use `quality.score`. Google Quality Score, 1-10. Null when unrated."},"quality":{"type":"object","description":"Google Quality Score and the three component ratings behind it\n(`ad_group_criterion.quality_info`). Every field is null until Google has rated the\nkeyword: a keyword with too little traffic is unrated, and negatives are never rated.\nGoogle's own UNKNOWN / UNSPECIFIED buckets are reported as null so \"unrated\" has a\nsingle representation.\n","properties":{"score":{"type":["integer","null"],"description":"Quality Score, 1-10."},"expectedCtr":{"type":["string","null"],"enum":["BELOW_AVERAGE","AVERAGE","ABOVE_AVERAGE",null],"description":"How the click-through rate compares with other ads in the same position (`search_predicted_ctr`)."},"adRelevance":{"type":["string","null"],"enum":["BELOW_AVERAGE","AVERAGE","ABOVE_AVERAGE",null],"description":"How closely the ad matches the intent behind the search (`creative_quality_score`)."},"landingPageExperience":{"type":["string","null"],"enum":["BELOW_AVERAGE","AVERAGE","ABOVE_AVERAGE",null],"description":"How relevant and useful the landing page is to people who click (`post_click_quality_score`)."}}},"syncedAt":{"type":["string","null"],"format":"date-time"},"metrics":{"type":["object","null"],"description":"Trailing 30-day window. Null on rows synced before the metrics columns existed (re-synced on the keyword's next daily sweep).","properties":{"windowDays":{"type":"integer"},"clicks":{"type":"integer"},"impressions":{"type":"integer"},"cost":{"type":"number","description":"Account currency, not USD-normalized"},"conversions":{"type":"number"},"firstPageCpc":{"type":["number","null"],"description":"Account currency"},"firstPositionCpc":{"type":["number","null"],"description":"Account currency"}}}}},"AdScheduleWindow":{"type":"object","description":"One ad schedule window as Google stores it. Half-open: it is exclusive of the end minute, so 09:00-12:00 and 12:00-17:00 are adjacent, not overlapping.","properties":{"criterionId":{"type":"string","description":"Google campaign criterion id. Changes whenever the window is rewritten, because Google cannot edit a schedule in place."},"resourceName":{"type":"string"},"dayOfWeek":{"type":"string","enum":["MONDAY","TUESDAY","WEDNESDAY","THURSDAY","FRIDAY","SATURDAY","SUNDAY"]},"startHour":{"type":"integer","minimum":0,"maximum":23},"startMinute":{"type":"integer","enum":[0,15,30,45]},"endHour":{"type":"integer","minimum":0,"maximum":24,"description":"24 means midnight at the end of the day."},"endMinute":{"type":"integer","enum":[0,15,30,45]},"bidModifier":{"type":["number","null"],"description":"Bid adjustment for this window, 0.1-10.0. Null when the window runs at the campaign bid."}}},"KeywordEntry":{"description":"A Google Search keyword: a bare string (BROAD match), or an object naming the match type.","oneOf":[{"type":"string","minLength":1,"maxLength":80,"description":"Keyword text; defaults to BROAD match"},{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":80},"matchType":{"type":"string","enum":["exact","phrase","broad"],"description":"Defaults to broad. Accepted in any case (EXACT, Exact) and stored lowercase."}}}]},"EventDestination":{"type":"object","properties":{"id":{"type":"string","description":"Event destination ID, used to delete it."},"profileId":{"type":"string"},"accountId":{"type":"string"},"destinationId":{"type":"string","description":"Platform destination (pixel, conversion action, rule, ...)."},"eventNames":{"type":["array","null"],"items":{"type":"string"},"description":"Event names forwarded to this destination; null forwards every event."},"createdAt":{"type":"string","format":"date-time"}}},"ConversionEvent":{"type":"object","description":"A single conversion event to relay to the ad platform. All PII fields\n(email, phone, names) are hashed with SHA-256 server-side using each\nplatform's normalization rules before they leave Zernio. Callers send\nplaintext.\n","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. Custom strings work only on platforms that accept custom events: Meta, OpenAI Ads and Reddit.\n\nPer-platform behavior:\n\n- Meta: free-form; standard names match Meta's built-ins.\n- Google: ignored. The conversion action's category determines the type.\n- LinkedIn: ignored. The conversion rule's `type` is locked to the destination.\n- OpenAI Ads: a fixed subset (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.\n- Reddit: Purchase, Lead, CompleteRegistration (SIGN_UP), AddToCart, AddToWishlist, ViewContent, Search and PageView (PAGE_VISIT) map onto Reddit's tracking types. Anything else is sent as a CUSTOM event with the name preserved.\n","example":"Purchase"},"eventTime":{"type":"integer","description":"When the conversion happened, in unix seconds.","example":1744732800},"eventId":{"type":"string","description":"Unique dedup key. Use the same eventId on pixel + CAPI to prevent double-counting. Mapped to:\n\n- Meta: event_id.\n- Google: transactionId.\n- LinkedIn: eventId. LinkedIn deduplicates against Insight Tag events with the same eventId; the Insight Tag event wins when both arrive.\n- Reddit: `metadata.conversion_id` (Reddit's dedup key against Reddit Pixel events).\n","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\nserver-side for Meta and Google. Sent as plaintext to LinkedIn\n(LinkedIn's Conversions API spec requires the raw value).\nMaximum effective list size on LinkedIn is 1.\n"},"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\nfor Conversion Leads CRM events: send it with\n`actionSource: 'crm'` and\n`platformData: { event_source: 'crm', lead_event_source: '<CRM name>' }`.\nForwarded unhashed to Meta's `user_data.lead_id`. Meta only.\n"},"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\nparsing `li_fat_id` from landing-page URLs after the\nadvertiser enables enhanced conversion tracking on the\nLinkedIn Insight Tag. Sent to LinkedIn as the\nLINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID userId. Opaque\ntoken, not hashed.\n"},"epik":{"type":"string","description":"Pinterest click ID (the `epik` URL param or `_epik` cookie). Sent to Pinterest as `click_id`, not hashed."},"rdt_cid":{"type":"string","description":"Reddit click ID (the `rdt_cid` URL param Reddit adds to ad clicks). Sent to Reddit as `click_id`, not hashed."},"rdt_uuid":{"type":"string","description":"Reddit Pixel browser id (the `_rdt_uuid` first-party cookie). Sent to Reddit as `user.uuid`, 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)."},"campaign":{"type":"object","additionalProperties":false,"description":"The ad campaign behind the event, when you know it. Read only by `POST /v1/events`, which ties the event to the campaign named by `campaign.id`, then by the `utm_campaign` of `sourceUrl`, then by `campaign.name`. See its Storage notes for how the event then counts.","properties":{"id":{"type":"string","maxLength":64,"description":"Platform campaign ID."},"name":{"type":"string","maxLength":300,"description":"Campaign name as it appears on the ad platform (case-insensitive)."}}},"actionSource":{"type":"string","enum":["web","app","offline","crm","phone_call","system_generated","business_messaging"],"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. `business_messaging` (Meta) marks an event from a WhatsApp, Messenger or Instagram Direct conversation and needs `messaging`."},"messaging":{"type":"object","description":"Meta only, read when `actionSource` is `business_messaging` (Conversions API for Business Messaging).\n\n- `channel` is sent as the event's `messaging_channel` (`instagram_direct` goes out as `instagram`).\n- Each id lands in Meta's `user_data` unhashed. An id that does not belong to `channel` is ignored.\n\nMeta accepts only its business messaging event names here: `LeadSubmitted`, `QualifiedLead`, `Purchase`, `AddToCart`, `InitiateCheckout`, `ViewContent`, `OrderCreated`, `OrderShipped`, `OrderDelivered`, `OrderCanceled`, `OrderReturned`, `CartAbandoned`, `RatingProvided`, `ReviewProvided`. `eventName` is forwarded unchanged.\n","required":["channel"],"properties":{"channel":{"type":"string","enum":["whatsapp","messenger","instagram_direct"]},"wabaId":{"type":"string","description":"WhatsApp only. WhatsApp Business Account id, sent as `whatsapp_business_account_id`."},"ctwaClid":{"type":"string","description":"WhatsApp only. Click-to-WhatsApp click id from the first inbound message referral, sent as `ctwa_clid`."},"pageId":{"type":"string","description":"Messenger: Facebook Page id, sent as `page_id`. Instagram Direct: when `instagramBusinessAccountId` is absent, Zernio reads the Instagram professional account linked to this Page and sends its id as `ig_account_id`; if none is linked or the lookup fails, `page_id` is sent instead."},"instagramBusinessAccountId":{"type":"string","description":"Instagram Direct only. Instagram professional account id (`instagram_business_account` on the Page), sent as `ig_account_id` next to `ig_sid`."},"pageScopedUserId":{"type":"string","description":"Messenger only. The page-scoped user id (PSID) your Messenger webhook gives for the person, sent as `page_scoped_user_id` next to `page_id`."},"instagramScopedUserId":{"type":"string","description":"Instagram Direct only. The Instagram-scoped user id (IGSID) your Instagram messaging webhook gives for the person, sent as `ig_sid`."}}},"platformData":{"type":"object","additionalProperties":true,"description":"Escape hatch for platform-specific fields we haven't normalized.\nOn Meta, keys are shallow-merged into `custom_data` only: fields\nZernio already builds (`value`, `currency`, `contents`,\n`num_items`) always win on collision, and `user_data` (hashed\nmatch keys) is never touched. Use first-class fields (e.g.\n`user.leadId`) for anything that must reach `user_data`.\n"}}},"ConversionDestination":{"type":"object","description":"A discoverable conversion destination on an ad platform: a Meta pixel,\nGoogle conversion action, or LinkedIn conversion rule. Returned by\n`listConversionDestinations`, `getConversionDestination`,\n`createConversionDestination`, and `updateConversionDestination`.\n","required":["id","name"],"properties":{"id":{"type":"string","description":"Platform-native identifier. Pass back as `destinationId` on event\nsend and as the path segment on CRUD endpoints.\n"},"name":{"type":"string"},"type":{"type":"string","description":"Present when the platform locks the event type/category to the\ndestination (Google conversion actions, LinkedIn conversion rules).\nAbsent for Meta pixels (which accept any event name per request).\n"},"status":{"type":"string","enum":["active","inactive"],"description":"For LinkedIn, `inactive` means the rule is soft-deleted (`enabled: false`).\n"},"adAccountId":{"type":"string","description":"Set by adapters whose destinations are scoped to a specific ad\naccount (LinkedIn). Pass back on subsequent CRUD calls to\nidentify the parent ad account.\n"}}},"ConversionAction":{"type":"object","description":"A Google Ads conversion action, e.g. a WEBPAGE conversion created via\n`createConversionAction`. Returned by `listConversionActions` and\n`createConversionAction`.\n","required":["id","name","type","status","category","tagSnippets"],"properties":{"id":{"type":"string","description":"Google Ads conversion action id."},"name":{"type":"string"},"type":{"type":"string","description":"Google's ConversionActionType, e.g. WEBPAGE, UPLOAD_CLICKS."},"status":{"type":"string","description":"Google's ConversionActionStatus, e.g. ENABLED, REMOVED, HIDDEN."},"category":{"type":"string","description":"Google's ConversionActionCategory, e.g. DEFAULT, PURCHASE, LEAD."},"origin":{"type":"string","description":"Google's ConversionOrigin, e.g. WEBSITE, APP. Together with category it names the goal the action belongs to (see GET /v1/ads/conversions/goals)."},"primaryForGoal":{"type":"boolean","description":"true = primary (counts toward bidding when its goal is biddable), false = secondary. Change it with PATCH /v1/ads/conversions/actions/{actionId}."},"defaultValue":{"type":"number","description":"Value recorded when the conversion carries none."},"defaultCurrency":{"type":"string","description":"ISO 4217 currency of defaultValue."},"alwaysUseDefaultValue":{"type":"boolean","description":"true = defaultValue is used even when the conversion sends its own value."},"countingType":{"type":"string","description":"Google's ConversionActionCountingType: ONE_PER_CLICK or MANY_PER_CLICK."},"clickThroughLookbackWindowDays":{"type":"integer","description":"Days after an ad click a conversion is still credited (1 to 90)."},"viewThroughLookbackWindowDays":{"type":"integer","description":"Days after an ad view a conversion is still credited (1 to 30)."},"tagSnippets":{"type":"array","description":"The code a customer pastes onto their site. Present for types\nGoogle generates a snippet for (e.g. WEBPAGE); empty otherwise.\n","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"Google's TrackingCodeType, e.g. WEBPAGE."},"pageFormat":{"type":"string","description":"Google's TrackingCodePageFormat, e.g. HTML, AMP."},"globalSiteTag":{"type":"string","description":"The gtag.js snippet to install once per site."},"eventSnippet":{"type":"string","description":"The per-conversion-page snippet that fires the event."}}}}}},"CtwaSingleResponse":{"type":"object","description":"Response returned by `POST /v1/ads/ctwa` when the request used the\nsingle-creative shape (top-level headline / body / imageUrl|video).\n`adType` is the union discriminator.\n","required":["adType","ad","message"],"properties":{"adType":{"type":"string","enum":["single"]},"ad":{"type":"object","description":"The persisted Ad document."},"message":{"type":"string"},"recoveredWrites":{"$ref":"#/components/schemas/MetaRecoveredWrites"},"warnings":{"type":"array","items":{"type":"string"},"description":"Present when Meta created the ad set differently from the request:\n\n- Multi-destination ad set (`destinations` including whatsapp) that Meta kept without the requested `whatsappPhoneNumber` in its promoted_object, which an existing ad set cannot change. A WhatsApp-only ad set returns no such warning, because every ad routes conversations by the number on its WhatsApp button.\n- The ad set joined a CBO campaign (`existingCampaignId`) whose own bid strategy applies, so a different `bidStrategy` or a `roasAverageFloor` that strategy cannot take was not applied.\n- An entry starting with `activation_failed:`: Meta refused the final switch to ACTIVE. Nothing was deleted. The entry names what was kept PAUSED and what was switched ACTIVE, and quotes Meta's error and the status calls that switch the PAUSED ones on later.\n"}}},"CtwaMultiResponse":{"type":"object","description":"Response returned by `POST /v1/ads/ctwa` when the request used the\nmulti-creative shape (`creatives[]`). N persisted Ad documents share\nthe returned `platformCampaignId` and `platformAdSetId`. `adType` is\nthe union discriminator.\n","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\n`platformCampaignId` and `platformAdSetId`.\n","items":{"type":"object"}},"platformCampaignId":{"type":"string"},"platformAdSetId":{"type":"string"},"message":{"type":"string"},"recoveredWrites":{"$ref":"#/components/schemas/MetaRecoveredWrites"},"warnings":{"type":"array","items":{"type":"string"},"description":"Present when Meta created the ad set differently from the request:\n\n- A multi-destination ad set (`destinations` including whatsapp) that Meta kept without the requested `whatsappPhoneNumber` in its promoted_object, which an existing ad set cannot change. A WhatsApp-only ad set returns no such warning, because every ad routes conversations by the number on its WhatsApp button.\n- The ad set joined a CBO campaign (`existingCampaignId`) whose own bid strategy applies, so a different `bidStrategy`, or a `roasAverageFloor` that strategy cannot take, was not applied.\n- An entry starting with `activation_failed:` when Meta refused the final switch to ACTIVE. Nothing was deleted; the entry names what was kept PAUSED and what was switched ACTIVE, and quotes Meta's error and the status calls that switch the PAUSED ones on later.\n"}}},"CustomConversion":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"rule":{"type":["object","null"],"description":"Meta's rule, parsed back from the string Meta stores."},"customEventType":{"type":["string","null"]},"pixelId":{"type":["string","null"],"description":"Meta's event_source_id, the pixel the rule reads from."},"isArchived":{"type":"boolean"},"defaultConversionValue":{"type":["number","null"],"description":"Value Meta assigns a conversion that carries none, in the ad account's currency."}}},"CustomConversionResult":{"type":"object","properties":{"adAccountId":{"type":"string"},"customConversionId":{"type":"string","description":"Drops straight into promotedObject.customConversionId on POST /v1/ads/create."},"reused":{"type":"boolean","description":"True when an existing conversion matched name + pixelId; the response is then a 200."},"customConversion":{"$ref":"#/components/schemas/CustomConversion"}}},"Blog":{"type":"object","description":"A blog container on the connected platform. All content lives on the platform; Zernio proxies it and stores nothing.","properties":{"id":{"type":"string","description":"Platform-native blog id. Shopify uses a numeric blog id. WordPress.com uses the numeric site id; self-hosted WordPress and Wix use `1`, scoped to the connected account. Webflow uses the CMS collection id."},"platform":{"type":"string","enum":["shopify","wordpress","wix","webflow"]},"title":{"type":"string"},"handle":{"type":"string","description":"URL slug on Shopify and Webflow (the collection slug); site hostname on WordPress and Wix."}}},"BlogArticle":{"type":"object","description":"An article inside a blog on the connected platform.","properties":{"id":{"type":"string","description":"Platform-native article/post id: numeric on Shopify and WordPress, a GUID on Wix, a hex item id on Webflow."},"blogId":{"type":"string","description":"Platform-native id of the blog the article belongs to."},"platform":{"type":"string","enum":["shopify","wordpress","wix","webflow"]},"title":{"type":"string"},"bodyHtml":{"type":["string","null"],"description":"Article body as HTML. Wix stores rich content, converted from and to HTML; Wix lists return null (get the article for its body)."},"handle":{"type":"string","description":"URL slug of the article."},"url":{"type":["string","null"],"description":"WordPress and Wix. Public URL of the article while it is published; null for drafts and scheduled posts, and on a Wix site that is not published yet."},"tags":{"type":"array","items":{"type":"string"},"description":"Tag names. On WordPress and Wix, missing tag names are created and matching is case-insensitive."},"author":{"type":["string","null"],"description":"Shopify author display name, numeric WordPress user id serialized as a string, or Wix site member id. Wix posts without one are attributed to the site's default author."},"excerpt":{"type":["string","null"],"description":"Short summary shown in blog listings."},"image":{"type":["object","null"],"description":"Featured image.","properties":{"url":{"type":"string"},"altText":{"type":["string","null"]}}},"isPublished":{"type":"boolean","description":"False while the article is a draft or its publish date is still in the future."},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Publication time. On WordPress this is present only when status is `publish`; null for drafts, pending/private posts, and scheduled posts."},"status":{"type":"string","enum":["publish","future","draft","pending","private"],"description":"WordPress and Wix. Post status (`future` = scheduled, `pending` = in review on Wix); omitted for Shopify."},"publishDate":{"type":["string","null"],"format":"date-time","description":"WordPress and Wix. Scheduled publication time in UTC when status is `future`; null for other statuses and omitted for Shopify."},"createdAt":{"type":["string","null"],"format":"date-time","description":"Creation time when the platform exposes one. WordPress returns null because its core date is the editable publication date."},"updatedAt":{"type":["string","null"],"format":"date-time","description":"Last modification time. WordPress returns modified_gmt as UTC."}}},"ProductImage":{"type":"object","properties":{"url":{"type":"string"},"altText":{"type":["string","null"]}}},"ProductVariant":{"type":"object","description":"A purchasable variant of a product (one per option combination).","properties":{"id":{"type":"string","description":"Platform-native variant id (numeric string for Shopify)."},"title":{"type":"string","description":"Option combination label, e.g. \"S / Blue\"."},"sku":{"type":["string","null"]},"barcode":{"type":["string","null"]},"price":{"type":"string","description":"Decimal amount in the store currency, e.g. \"19.90\"."},"compareAtPrice":{"type":["string","null"],"description":"Strike-through price; null when the variant is not on sale."},"inventoryQuantity":{"type":["integer","null"],"description":"Units on hand across locations; null when inventory is not tracked."},"availableForSale":{"type":"boolean"},"selectedOptions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}}}}}},"Product":{"type":"object","description":"A product on the connected platform with its variants, options and images. All data lives on the platform; Zernio proxies it and stores nothing.","properties":{"id":{"type":"string","description":"Platform-native product id (numeric string for Shopify)."},"platform":{"type":"string","enum":["shopify"]},"title":{"type":"string"},"handle":{"type":"string","description":"URL slug of the product."},"descriptionHtml":{"type":["string","null"],"description":"Product description as HTML."},"vendor":{"type":["string","null"]},"productType":{"type":["string","null"],"description":"Free-text product type as set on the store."},"tags":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","draft","archived"]},"featuredImage":{"oneOf":[{"$ref":"#/components/schemas/ProductImage"},{"type":"null"}]},"images":{"type":"array","description":"First 20 images in the product media, in store order.","items":{"$ref":"#/components/schemas/ProductImage"}},"options":{"type":"array","description":"Option axes (e.g. Size, Color) and their values.","items":{"type":"object","properties":{"name":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}}}},"variants":{"type":"array","description":"First 100 variants.","items":{"$ref":"#/components/schemas/ProductVariant"}},"seo":{"type":"object","properties":{"title":{"type":["string","null"]},"description":{"type":["string","null"]}}},"totalInventory":{"type":["integer","null"]},"onlineStoreUrl":{"type":["string","null"],"description":"Public storefront URL; null while the product is not published to the online store."},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"publishedAt":{"type":["string","null"],"format":"date-time"}}},"CommerceMoney":{"type":"object","description":"An exact amount of money. The amount is a decimal string so cents are never lost to floating point.","required":["amount","currency"],"properties":{"amount":{"type":"string","example":"19.90"},"currency":{"type":"string","description":"ISO 4217 code. Never null: the store currency is filled in when the platform omits it.","example":"USD"}}},"CommerceCapability":{"type":"string","description":"An operation a store supports. Calling an operation outside this list answers 400 platform_not_supported.","enum":["products.read","products.create","products.update","products.status","products.price","products.variants","products.images","products.images_remove","collections.read","collections.write","collections.metafields","metafields.read","metafields.write","pages.read","pages.write","inventory.read","inventory.write","channels.read","channels.write","discounts.read","discounts.write","discounts.codes","navigation.read","navigation.write","metaobjects.read","metaobjects.write","markets.read","markets.write","marketing.write","orders.read"]},"CommerceImage":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Media id, used to reorder or remove images. Null for collection images."},"url":{"type":"string"},"altText":{"type":["string","null"]}}},"CommerceMetafield":{"type":"object","required":["namespace","key","type","value"],"properties":{"namespace":{"type":"string"},"key":{"type":"string"},"type":{"type":"string","description":"Platform value type, e.g. single_line_text_field, number_integer, json."},"value":{"type":"string","description":"The value serialized as a string, JSON for structured types."}}},"CommercePage":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"platform":{"type":"string","enum":["shopify"]},"title":{"type":"string"},"handle":{"type":"string"},"bodyHtml":{"type":"string"},"isPublished":{"type":"boolean"},"publishedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}}},"CommerceLocation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"isActive":{"type":"boolean"},"fulfillsOnlineOrders":{"type":"boolean"},"address":{"type":"object","properties":{"line1":{"type":["string","null"]},"line2":{"type":["string","null"]},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"postalCode":{"type":["string","null"]},"countryCode":{"type":["string","null"]},"phone":{"type":["string","null"]}}}}},"CommerceInventoryItem":{"type":"object","properties":{"productId":{"type":"string"},"variantId":{"type":"string"},"sku":{"type":["string","null"]},"tracked":{"type":"boolean","description":"False when the platform does not count stock for the variant."},"levels":{"type":"array","items":{"type":"object","properties":{"locationId":{"type":"string"},"available":{"type":["integer","null"]},"onHand":{"type":["integer","null"]},"committed":{"type":["integer","null"],"description":"Reserved for unfulfilled orders."},"incoming":{"type":["integer","null"]}}}}}},"CommerceChannel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"CommerceOrderStatus":{"type":"string","description":"Where the order stands. The raw platform value is returned next to it as platformStatus.","enum":["pending_payment","on_hold","awaiting_fulfillment","partially_fulfilled","in_transit","delivered","completed","cancelled"]},"CommerceTaxLine":{"type":"object","properties":{"title":{"type":"string","example":"TVA 20%"},"ratePercent":{"type":["number","null"],"description":"Percent, e.g. 20 for 20%. Null when the platform does not say."},"amount":{"$ref":"#/components/schemas/CommerceMoney"}}},"CommerceAddress":{"type":"object","properties":{"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"company":{"type":["string","null"]},"phone":{"type":["string","null"]},"line1":{"type":["string","null"]},"line2":{"type":["string","null"]},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"postalCode":{"type":["string","null"]},"countryCode":{"type":["string","null"],"description":"ISO 3166-1 alpha-2."}}},"CommerceOrderChargeLine":{"type":"object","description":"A shipping or fee line.","properties":{"id":{"type":"string"},"title":{"type":"string"},"amount":{"$ref":"#/components/schemas/CommerceMoney","description":"Before discounts."},"discountTotal":{"$ref":"#/components/schemas/CommerceMoney"},"taxLines":{"type":"array","items":{"$ref":"#/components/schemas/CommerceTaxLine"}}}},"CommerceOrderVisit":{"type":"object","description":"A store session that led to the order.","properties":{"occurredAt":{"type":["string","null"],"format":"date-time","description":"Null on WooCommerce, which records the session start without a timezone."},"landingUrl":{"type":["string","null"],"description":"The first page of the session, with its query string."},"referrerUrl":{"type":["string","null"]},"source":{"type":["string","null"],"description":"Where the visit came from, as the platform names it.","example":"instagram"},"sourceType":{"type":["string","null"],"description":"Shopify marketing tactic (e.g. SOCIAL, AD, SEARCH) or WooCommerce source type (utm, organic, referral, typein, admin)."},"utm":{"type":["object","null"],"description":"Null when the landing URL carried no UTM parameters.","properties":{"source":{"type":["string","null"]},"medium":{"type":["string","null"]},"campaign":{"type":["string","null"]},"term":{"type":["string","null"]},"content":{"type":["string","null"]}}}}},"CommerceOrderAttribution":{"type":"object","description":"Where the order came from. Shopify reads it from the customer journey, WooCommerce from its order attribution (WooCommerce 8.5+ with the feature on, orders placed after it was turned on).","properties":{"ready":{"type":"boolean","description":"False while Shopify is still attributing a new order. No webhook fires when it becomes true, so read the order again later. Always true on WooCommerce."},"firstVisit":{"description":"The first session before the order. Shopify only; WooCommerce records the last session alone.","oneOf":[{"$ref":"#/components/schemas/CommerceOrderVisit"},{"type":"null"}]},"lastVisit":{"description":"The last session before the order.","oneOf":[{"$ref":"#/components/schemas/CommerceOrderVisit"},{"type":"null"}]},"customAttributes":{"type":"array","description":"Shopify cart and note attributes, or WooCommerce public order meta.","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}}}},"CommerceOrder":{"type":"object","description":"An order with what an invoice needs. Every amount is in `currency`, the store currency.","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"platform":{"type":"string","enum":["shopify","woocommerce"]},"number":{"type":"string","description":"The number the merchant and buyer see.","example":"#1001"},"status":{"$ref":"#/components/schemas/CommerceOrderStatus"},"platformStatus":{"type":"string","description":"Shopify fulfilment status (e.g. UNFULFILLED) or WooCommerce order status (e.g. processing)."},"paymentStatus":{"oneOf":[{"type":"string","enum":["pending","authorized","partially_paid","paid","partially_refunded","refunded","voided","failed"]},{"type":"null"}]},"platformPaymentStatus":{"type":["string","null"],"description":"Shopify financial status. Null on WooCommerce, where payment is read from the order status."},"currency":{"type":"string","example":"EUR"},"taxesIncluded":{"type":"boolean","description":"Whether line item and shipping amounts include tax. Always false on WooCommerce, whose API returns amounts before tax whatever the store displays (platformData.pricesIncludeTax)."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"paidAt":{"type":["string","null"],"format":"date-time","description":"WooCommerce only; null on Shopify."},"cancelledAt":{"type":["string","null"],"format":"date-time","description":"Shopify only; null on WooCommerce."},"cancelReason":{"type":["string","null"]},"subtotal":{"$ref":"#/components/schemas/CommerceMoney","description":"Line items before order discounts and shipping."},"discountTotal":{"$ref":"#/components/schemas/CommerceMoney"},"shippingTotal":{"$ref":"#/components/schemas/CommerceMoney"},"taxTotal":{"$ref":"#/components/schemas/CommerceMoney"},"total":{"$ref":"#/components/schemas/CommerceMoney"},"refundedTotal":{"$ref":"#/components/schemas/CommerceMoney"},"discountCodes":{"type":"array","items":{"type":"string"}},"paymentMethods":{"type":"array","items":{"type":"string"}},"customer":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"description":"Null for guest checkouts."},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]}}},"billingAddress":{"oneOf":[{"$ref":"#/components/schemas/CommerceAddress"},{"type":"null"}]},"shippingAddress":{"oneOf":[{"$ref":"#/components/schemas/CommerceAddress"},{"type":"null"}]},"buyerNote":{"type":["string","null"]},"attribution":{"$ref":"#/components/schemas/CommerceOrderAttribution"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"productId":{"type":["string","null"],"description":"Null when the product was deleted."},"variantId":{"type":["string","null"]},"sku":{"type":["string","null"]},"title":{"type":"string"},"variantTitle":{"type":["string","null"]},"quantity":{"type":"integer","description":"As ordered; refunded units are listed under refunds."},"unitPrice":{"$ref":"#/components/schemas/CommerceMoney","description":"Before discounts."},"subtotal":{"$ref":"#/components/schemas/CommerceMoney","description":"unitPrice x quantity."},"discountTotal":{"$ref":"#/components/schemas/CommerceMoney"},"total":{"$ref":"#/components/schemas/CommerceMoney","description":"subtotal minus discountTotal."},"taxLines":{"type":"array","items":{"$ref":"#/components/schemas/CommerceTaxLine"}}}}},"shippingLines":{"type":"array","items":{"$ref":"#/components/schemas/CommerceOrderChargeLine"}},"feeLines":{"type":"array","description":"WooCommerce fees. Always empty on Shopify.","items":{"$ref":"#/components/schemas/CommerceOrderChargeLine"}},"taxLines":{"type":"array","description":"Order tax by rate, line items and shipping together.","items":{"$ref":"#/components/schemas/CommerceTaxLine"}},"refunds":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"type":["string","null"],"format":"date-time"},"note":{"type":["string","null"]},"amount":{"$ref":"#/components/schemas/CommerceMoney"},"lineItems":{"type":"array","items":{"type":"object","properties":{"lineItemId":{"type":"string"},"quantity":{"type":"integer"},"amount":{"$ref":"#/components/schemas/CommerceMoney","description":"Before tax."}}}}}}},"fulfillments":{"type":"array","items":{"type":"object","properties":{"carrierName":{"type":["string","null"]},"trackingNumber":{"type":["string","null"]},"trackingUrl":{"type":["string","null"]}}}},"platformData":{"type":["object","null"],"additionalProperties":true,"description":"Platform-only fields. Null when the platform has none."}}},"CommerceDiscount":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"platform":{"type":"string","enum":["shopify"]},"title":{"type":"string"},"method":{"type":"string","enum":["code","automatic"]},"type":{"type":"string","enum":["percentage","fixed_amount","free_shipping","buy_x_get_y","app"]},"codes":{"type":"array","items":{"type":"string"},"description":"The first 10 codes; codeCount has the total."},"codeCount":{"type":["integer","null"]},"value":{"description":"Null for free shipping, buy-X-get-Y and app discounts.","oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["percentage"]},"percentage":{"type":"number","example":15}}},{"type":"object","properties":{"type":{"type":"string","enum":["fixed_amount"]},"amount":{"$ref":"#/components/schemas/CommerceMoney"},"appliesOnEachItem":{"type":"boolean"}}},{"type":"null"}]},"appliesTo":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["all","products","collections"]},"productIds":{"type":"array","items":{"type":"string"}},"variantIds":{"type":"array","items":{"type":"string"}},"collectionIds":{"type":"array","items":{"type":"string"}}}},"minimum":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["subtotal","quantity"]},"amount":{"$ref":"#/components/schemas/CommerceMoney"},"quantity":{"type":"integer"}}},"usageLimit":{"type":["integer","null"]},"oncePerCustomer":{"type":"boolean"},"usageCount":{"type":"integer"},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","enum":["active","scheduled","expired"]},"platformStatus":{"type":"string"},"summary":{"type":"string"},"platformData":{"type":["object","null"],"additionalProperties":true}}},"CommerceRedirect":{"type":"object","properties":{"id":{"type":"string"},"path":{"type":"string"},"target":{"type":"string"}}},"CommerceMenuItem":{"type":"object","properties":{"id":{"type":["string","null"]},"title":{"type":"string"},"type":{"type":"string","enum":["frontpage","collection","collections","product","catalog","page","blog","article","search","shop_policy","http","metaobject","customer_account_page"]},"url":{"type":["string","null"]},"resourceId":{"type":["string","null"],"description":"The linked product, collection, page, blog, article or metaobject id."},"items":{"type":"array","items":{"$ref":"#/components/schemas/CommerceMenuItem"}}}},"CommerceMenuItemInput":{"type":"object","required":["title","type"],"properties":{"title":{"type":"string"},"type":{"type":"string","enum":["frontpage","collection","collections","product","catalog","page","blog","article","search","shop_policy","http","metaobject","customer_account_page"]},"url":{"type":"string","description":"For http items."},"resourceId":{"type":"string","description":"For product, collection, page, blog, article and metaobject items."},"items":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/CommerceMenuItemInput"}}}},"CommerceMenu":{"type":"object","properties":{"id":{"type":"string"},"handle":{"type":"string"},"title":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CommerceMenuItem"}}}},"CommerceMetaobjectDefinition":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"required":{"type":"boolean"}}}}}},"CommerceMetaobject":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"handle":{"type":"string"},"displayName":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"value":{"type":["string","null"]}}}}}},"CommerceMarket":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"status":{"type":"string","enum":["active","draft"]},"type":{"type":"string"}}},"CommercePriceList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"currency":{"type":"string"}}},"CommerceStore":{"type":"object","required":["accountId","platform","name","domain","url","currency","country","capabilities","missingCapabilities","grantPermissionsUrl"],"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id of the store."},"platform":{"type":"string","enum":["shopify","woocommerce"]},"name":{"type":"string"},"domain":{"type":"string","description":"The platform domain of the store, e.g. my-store.myshopify.com."},"url":{"type":["string","null"],"description":"Public storefront URL."},"currency":{"type":"string","description":"ISO 4217 code the store sells in."},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2 country of the store."},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/CommerceCapability"}},"missingCapabilities":{"type":"array","description":"Capabilities the platform supports that this store has not granted yet.","items":{"$ref":"#/components/schemas/CommerceCapability"}},"grantPermissionsUrl":{"type":["string","null"],"description":"Shopify: a page in the Shopify admin where the store owner approves the permissions missingCapabilities need, on the existing install (no reinstall; they can revoke them later). Null when nothing is missing or the store cannot grant them this way (a store connected with its own custom-app token)."}}},"CommerceProductStatus":{"type":"string","description":"Zernio product status. The platform value is returned as platformStatus. Shopify: ACTIVE, DRAFT and ARCHIVED map to the same names; UNLISTED maps to inactive.","enum":["active","draft","pending_review","rejected","inactive","archived","deleted"]},"CommerceVariant":{"type":"object","description":"A purchasable variant of a product (one per option combination).","properties":{"id":{"type":"string","description":"Platform-native variant id."},"title":{"type":"string","description":"Option combination label, e.g. \"S / Blue\"."},"sku":{"type":["string","null"]},"barcode":{"type":["string","null"]},"price":{"$ref":"#/components/schemas/CommerceMoney"},"compareAtPrice":{"description":"Strike-through price; null when the variant is not on sale.","oneOf":[{"$ref":"#/components/schemas/CommerceMoney"},{"type":"null"}]},"inventoryQuantity":{"type":["integer","null"],"description":"Units on hand; null when inventory is not tracked."},"availableForSale":{"type":["boolean","null"]},"options":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}}}}}},"CommerceProduct":{"type":"object","description":"A product on a connected store, in the platform-neutral shape.","properties":{"id":{"type":"string","description":"Platform-native product id."},"accountId":{"type":"string"},"platform":{"type":"string","enum":["shopify"]},"title":{"type":"string"},"descriptionHtml":{"type":["string","null"]},"handle":{"type":["string","null"],"description":"URL slug of the product."},"vendor":{"type":["string","null"]},"productType":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"status":{"$ref":"#/components/schemas/CommerceProductStatus"},"platformStatus":{"type":"string","description":"The raw status on the platform, e.g. ACTIVE on Shopify."},"featuredImage":{"oneOf":[{"$ref":"#/components/schemas/CommerceImage"},{"type":"null"}]},"images":{"type":"array","description":"First 20 images, in store order.","items":{"$ref":"#/components/schemas/CommerceImage"}},"options":{"type":"array","description":"Option axes (e.g. Size, Color) and their values.","items":{"type":"object","properties":{"name":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}}}},"variants":{"type":"array","description":"First 100 variants.","items":{"$ref":"#/components/schemas/CommerceVariant"}},"totalInventory":{"type":["integer","null"]},"url":{"type":["string","null"],"description":"Public storefront URL; null while the product is not published."},"seo":{"type":"object","properties":{"title":{"type":["string","null"]},"description":{"type":["string","null"]}}},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"publishedAt":{"type":["string","null"],"format":"date-time"},"platformData":{"type":["object","null"],"additionalProperties":true,"description":"Platform-only fields. Null when the platform has none."}}},"WebhookPayloadCommerceProduct":{"type":"object","properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string"},"event":{"type":"string","enum":["commerce.product.created","commerce.product.updated","commerce.product.deleted"]},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."},"store":{"type":"object","properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id of the store."},"platform":{"type":"string","enum":["shopify","woocommerce"]},"shopId":{"type":["string","null"],"description":"The platform id of the shop."}}},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["product"]},"id":{"type":"string","description":"Platform-native product id."},"status":{"description":"Zernio product status; null on delete.","oneOf":[{"$ref":"#/components/schemas/CommerceProductStatus"},{"type":"null"}]},"platformStatus":{"type":["string","null"],"description":"Raw platform status, e.g. ACTIVE; null on delete."}}}}},"WebhookPayloadCommerceOrder":{"type":"object","properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string"},"event":{"type":"string","enum":["commerce.order.created","commerce.order.updated","commerce.order.refunded"]},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"store":{"type":"object","properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id of the store."},"platform":{"type":"string","enum":["shopify","woocommerce"]},"shopId":{"type":["string","null"],"description":"The platform id of the shop."}}},"resource":{"type":"object","description":"Identifiers only, never buyer data: read the order with GET /v1/commerce/orders/{orderId}.","properties":{"type":{"type":"string","enum":["order"]},"id":{"type":"string","description":"Platform-native order id."},"status":{"description":"Zernio order status at the time of the change. Null on commerce.order.refunded from Shopify, and on WooCommerce refunds.","oneOf":[{"$ref":"#/components/schemas/CommerceOrderStatus"},{"type":"null"}]},"platformStatus":{"type":["string","null"],"description":"Raw platform status, e.g. UNFULFILLED on Shopify or processing on WooCommerce."}}}}},"WebhookPayloadContactTag":{"type":"object","required":["id","event","timestamp","contact","tag","source"],"properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Event id, the dedupe key."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"event":{"type":"string","enum":["contact.tag_added","contact.tag_removed"]},"timestamp":{"type":"string","format":"date-time"},"contact":{"type":"object","properties":{"id":{"type":"string","description":"Zernio contact id."}}},"tag":{"type":"string"},"source":{"type":"string","enum":["api","workflow","automation"],"description":"Who wrote the tag: the API or dashboard, a workflow add_tag / remove_tag node, or a comment-automation link click."}}},"WebhookPayloadContactFieldChanged":{"type":"object","required":["id","event","timestamp","contact","field","previousValue","value","source"],"properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Event id, the dedupe key."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"event":{"type":"string","enum":["contact.field_changed"]},"timestamp":{"type":"string","format":"date-time"},"contact":{"type":"object","properties":{"id":{"type":"string","description":"Zernio contact id."}}},"field":{"type":"string","description":"Custom field slug."},"previousValue":{"description":"Value before the write; null when the field was not set."},"value":{"description":"Value after the write; null when the field was removed."},"source":{"type":"string","enum":["api","workflow","automation"],"description":"Who wrote the field: the API or dashboard, a workflow set_field node, or an automation."}}},"WebhookPayloadSequenceEnrollment":{"type":"object","required":["id","event","timestamp","sequence","contact","enrollment"],"properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Event id, the dedupe key."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"event":{"type":"string","enum":["sequence.enrolled","sequence.exited"]},"timestamp":{"type":"string","format":"date-time"},"sequence":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"contact":{"type":"object","properties":{"id":{"type":"string","description":"Zernio contact id."}}},"enrollment":{"type":"object","properties":{"id":{"type":"string"}}},"exitReason":{"type":"string","enum":["completed","replied","manual","failed","unsubscribed"],"description":"sequence.exited only. completed: the last step was sent; replied: the contact replied and the sequence exits on reply; manual: unenrolled through the API; failed: the step kept failing to send; unsubscribed: the contact opted out."}}},"WebhookPayloadWorkflowRun":{"type":"object","required":["id","event","timestamp","workflow","execution","conversation","contact","trigger"],"properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Event id, the dedupe key."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"event":{"type":"string","enum":["workflow.run.started","workflow.run.completed","workflow.run.failed"]},"timestamp":{"type":"string","format":"date-time"},"workflow":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"],"description":"Null when the workflow was deleted while the run was live."}}},"execution":{"type":"object","properties":{"id":{"type":"string","description":"Workflow run (execution) id."},"status":{"type":"string","enum":["running","waiting","completed","exited","failed"],"description":"running on workflow.run.started; completed or exited (ended on purpose before the last node, e.g. a handoff) on workflow.run.completed; failed on workflow.run.failed."}}},"conversation":{"type":["object","null"],"description":"Null while a comment-triggered run has not sent the private reply that opens its conversation.","properties":{"id":{"type":"string"}}},"contact":{"type":["object","null"],"properties":{"id":{"type":"string","description":"Zernio contact id."}}},"trigger":{"type":"object","properties":{"type":{"type":["string","null"],"description":"The trigger node type, e.g. inbound_message (the default when the node sets none). Null when the workflow was deleted while the run was live."},"text":{"type":"string","description":"The inbound message that started the run, when there was one."}}},"error":{"type":"string","description":"workflow.run.failed only: which node failed and why."}}},"WebhookPayloadSupportRun":{"type":"object","required":["id","event","timestamp","run"],"properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Event id, the dedupe key."},"event":{"type":"string","enum":["support.run.completed","support.run.failed"]},"timestamp":{"type":"string","format":"date-time"},"run":{"$ref":"#/components/schemas/SupportRun"}}},"SupportRunUsage":{"type":"object","required":["inputTokens","outputTokens","cacheReadTokens","cacheWriteTokens"],"properties":{"inputTokens":{"type":"integer"},"outputTokens":{"type":"integer"},"cacheReadTokens":{"type":"integer"},"cacheWriteTokens":{"type":"integer"}}},"SupportRunDiagnosis":{"type":"object","required":["category","cause","fixSteps","docsLinks","whoMustAct"],"properties":{"category":{"type":"string","enum":["account_connection","content_rejected","rate_limited","platform_issue","zernio_issue","billing","configuration","how_to","other"],"description":"What kind of problem the answer describes. New values may be added: treat any value you do not recognize as `other`."},"cause":{"type":["string","null"],"description":"The cause the answer gives, in one sentence. Null when the answer reports no problem, for example a how-to question."},"fixSteps":{"type":"array","items":{"type":"string"},"description":"The steps the answer recommends, in order. Empty when it recommends none."},"docsLinks":{"type":"array","items":{"type":"string"},"description":"Links to docs.zernio.com that the answer itself cites. Empty when it cites none."},"whoMustAct":{"type":"string","enum":["integrator","end_user","zernio","platform","none"],"description":"Who has to act to resolve it: you (`integrator`), your end user, Zernio, the social platform, or nobody. New values may be added: treat any value you do not recognize as `none`."}}},"SupportRun":{"type":"object","required":["runId","threadId","status","stopReason","question","answer","diagnosis","usage","costUsd","maxCostUsd","createdAt","startedAt","finishedAt","supportTicket"],"properties":{"runId":{"type":"string","description":"Run id, a 24-character hex string."},"threadId":{"type":"string","description":"Conversation thread id. Send it back as `threadId` to ask a follow-up in the same thread."},"status":{"type":"string","enum":["queued","running","completed","needs_human","failed"],"description":"queued and running are in progress. needs_human means the assistant handed the question to a person instead of answering; when `supportTicket` is set, a Zernio teammate has been notified and will follow up by email."},"stopReason":{"type":["string","null"],"enum":["answered","human_review","cost_cap","deadline","max_iterations","error","expired",null],"description":"Why the run stopped. Null while it is in progress."},"question":{"type":["string","null"],"description":"The question as asked, with leading and trailing whitespace trimmed. Null only on runs created before this field was added."},"answer":{"type":["string","null"],"description":"The assistant's answer. Null while the run is in progress or when it failed."},"diagnosis":{"anyOf":[{"$ref":"#/components/schemas/SupportRunDiagnosis"},{"type":"null"}],"description":"The answer as structured fields you can route on. Null while in progress, when the run failed or went to a person (needs_human), or when no diagnosis could be produced."},"usage":{"$ref":"#/components/schemas/SupportRunUsage"},"costUsd":{"type":"number","description":"The exact amount charged for the question, in USD, never above `maxCostUsd`. 0 for a failed run."},"maxCostUsd":{"type":"number","description":"The cost cap this run was started with, in USD."},"createdAt":{"type":"string","format":"date-time"},"startedAt":{"type":["string","null"],"format":"date-time"},"finishedAt":{"type":["string","null"],"format":"date-time"},"supportTicket":{"type":["object","null"],"description":"Set when the assistant opened a support ticket with the Zernio team. Null otherwise. A teammate follows up by email with the user whose API key started the run.","required":["openedAt"],"properties":{"openedAt":{"type":"string","format":"date-time"}}},"pollAfterSeconds":{"type":"integer","description":"Seconds to wait before polling again. Present only while the run is queued or running."}}},"CommerceCollection":{"type":"object","description":"A product collection on a connected store.","properties":{"id":{"type":"string","description":"Platform-native collection id."},"accountId":{"type":"string"},"platform":{"type":"string","enum":["shopify","woocommerce"]},"title":{"type":"string"},"handle":{"type":["string","null"]},"descriptionHtml":{"type":["string","null"]},"image":{"oneOf":[{"$ref":"#/components/schemas/CommerceImage"},{"type":"null"}]},"sortOrder":{"type":"string","enum":["manual","best_selling","alpha_asc","alpha_desc","price_asc","price_desc","created","created_desc","most_relevant"]},"productCount":{"type":["integer","null"],"description":"Updates a few seconds after a membership change."},"seo":{"type":"object","properties":{"title":{"type":["string","null"]},"description":{"type":["string","null"]}}},"updatedAt":{"type":["string","null"],"format":"date-time"},"platformData":{"type":["object","null"],"additionalProperties":true}}},"CommerceCatalogSync":{"type":"object","description":"A store kept in sync with an ad-platform product catalog.","properties":{"id":{"type":"string"},"accountId":{"type":"string","description":"The store SocialAccount id."},"catalogPlatform":{"type":"string","enum":["meta"]},"catalogAccountId":{"type":"string","description":"The Meta login account whose token writes to the catalog."},"catalogId":{"type":"string"},"runStatus":{"type":"string","enum":["pending","running","succeeded","failed"]},"lastRunStartedAt":{"type":["string","null"],"format":"date-time"},"lastRunFinishedAt":{"type":["string","null"],"format":"date-time"},"lastError":{"type":["string","null"],"description":"Why the last run failed, or how many items Meta rejected in a run that otherwise succeeded. Null after a clean run."},"itemsSent":{"type":"integer","description":"Catalog items (one per variant) Meta accepted in the last full run."},"itemsSkipped":{"type":"integer","description":"Products the last full run could not list: not published to the online store or without an image."},"itemsDeleted":{"type":"integer","description":"Items the last full run removed because the store no longer has them."},"createdAt":{"type":"string","format":"date-time"}}},"BusinessAgentSettings":{"type":"object","description":"Meta Business Agent settings for one WhatsApp number, as Meta returns them.","required":["agent_id","channel","rollout"],"properties":{"agent_id":{"type":"string"},"channel":{"type":"string","example":"whatsapp"},"rollout":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean","description":"Whether the agent answers live conversations."}}},"handoff":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","description":"Whether the agent releases the thread after sending its handoff message."},"message":{"type":"string"},"message_selection":{"type":"string","enum":["DEFAULT","AGENT","CUSTOM"]}}},"followup":{"type":["object","null"],"properties":{"enabled":{"type":"boolean"},"followup_interval_in_seconds":{"type":"integer","enum":[0,300,900,1800,3600,7200,28800,86400]},"message":{"type":"string"}}},"ai_audience":{"type":["string","null"],"enum":["EVERYONE","ALLOWLISTED_ONLY",null],"description":"EVERYONE answers all consumers; ALLOWLISTED_ONLY answers only the allowlist and needs no payment method."},"never_say_phrases":{"type":"array","items":{"type":"string"},"description":"Exact phrases the agent must never say."}}},"BusinessAgentStatus":{"type":"object","description":"Where the merchant is in the Meta Business Agent setup for this number.","required":["eligible","termsAccepted","onboarded","enabled","agentId","settings","manualSteps","unverifiedSteps"],"properties":{"eligible":{"type":["boolean","null"],"description":"Whether the number can run the agent; null when the terms are not accepted yet (Meta refuses the check)."},"termsAccepted":{"type":"boolean","description":"False when Meta rejects calls because the merchant has not accepted the terms in WhatsApp Manager."},"onboarded":{"type":"boolean","description":"An agent exists on the number (onboard was called)."},"enabled":{"type":"boolean","description":"The agent answers live conversations."},"agentId":{"type":["string","null"]},"settings":{"oneOf":[{"$ref":"#/components/schemas/BusinessAgentSettings"},{"type":"null"}]},"manualSteps":{"type":"array","description":"Steps Meta keeps outside the API that Zernio can verify are still pending.","items":{"type":"object","required":["step","url","description"],"properties":{"step":{"type":"string","enum":["accept_terms"]},"url":{"type":"string","format":"uri"},"description":{"type":"string"}}}},"unverifiedSteps":{"type":"array","description":"Steps Meta keeps outside the API and exposes no state for, listed once an agent exists. Informational: Zernio cannot tell whether the merchant already did them.","items":{"type":"object","required":["step","url","description"],"properties":{"step":{"type":"string","enum":["attach_payment_method"]},"url":{"type":"string","format":"uri"},"description":{"type":"string"}}}}}},"BusinessAgentAllowlistEntry":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"consumer_phone_number":{"type":"string","description":"E.164 phone number."}}},"BusinessAgentBusinessInformation":{"type":"object","description":"Free-text facts the agent answers from; PUT replaces the whole object.","properties":{"payment_method":{"type":"string"},"return_policy":{"type":"string"},"purchase_info":{"type":"string"},"delivery_and_shipping":{"type":"string"},"business_description":{"type":"string"},"contact_info":{"type":["object","null"],"properties":{"email":{"type":"string"},"hours_of_operation":{"type":"string"},"address":{"type":"string"}}}}},"BusinessAgentFaqInput":{"type":"object","required":["question","answer"],"properties":{"question":{"type":"string","maxLength":1000,"description":"Phrase it the way a customer would ask it; one topic per entry."},"answer":{"type":"string","maxLength":8000,"description":"Self-contained; the agent retrieves entries independently."},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"BusinessAgentFaq":{"allOf":[{"$ref":"#/components/schemas/BusinessAgentFaqInput"},{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"created_at":{"type":"integer","description":"Unix seconds."}}}]},"BusinessAgentWebsiteInput":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"included_sub_domains":{"type":"array","items":{"type":"string"}},"included_url_patterns":{"type":"array","items":{"type":"string"},"description":"Only URLs containing one of these substrings are ingested."},"excluded_sub_domains":{"type":"array","items":{"type":"string"}},"excluded_url_patterns":{"type":"array","items":{"type":"string"}},"single_urls":{"type":"array","items":{"type":"string","format":"uri"},"description":"Crawl only these exact pages instead of the whole site."}}},"BusinessAgentWebsite":{"allOf":[{"$ref":"#/components/schemas/BusinessAgentWebsiteInput"},{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"crawl_status":{"type":"string","description":"not_started, pending, in_progress, completed, completed_no_data or failed (see crawl_error)."},"crawl_error":{"type":"string"},"pages_crawled":{"type":"integer"},"last_crawled_at":{"type":"integer","description":"Unix seconds."},"created_at":{"type":"integer","description":"Unix seconds."}}}]},"BusinessAgentKnowledgeFile":{"type":"object","required":["id","file_name"],"properties":{"id":{"type":"string"},"file_name":{"type":"string"}}},"BusinessAgentSkillInput":{"type":"object","required":["skill"],"properties":{"title":{"type":"string","maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","description":"Lowercase letters, digits and hyphens, e.g. greeting-skill."},"description":{"type":"string","maxLength":1024,"description":"When the agent should apply the skill."},"skill":{"type":"string","maxLength":20000,"description":"The instructions themselves. Avoid two skills that both claim priority for the same situation."}}},"BusinessAgentSkill":{"allOf":[{"$ref":"#/components/schemas/BusinessAgentSkillInput"},{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"channel":{"type":"string"},"created_at":{"type":"integer","description":"Unix seconds."},"status":{"type":"string","enum":["active","pending_review","blocked"],"description":"pending_review right after a write; blocked means Meta content review rejected it and the agent never applies it."}}}]},"BusinessAgentUiSkillInput":{"type":"object","required":["component_type","status","instruction"],"properties":{"title":{"type":"string"},"component_type":{"type":"string","enum":["carousel_quick_reply","carousel_url","cta_url","flow","image","interactive_list","interactive_reply_buttons","location","location_request"]},"status":{"type":"string","enum":["enabled","disabled"]},"instruction":{"type":"string","description":"When to send the component and everything needed to fill its fields."},"flow_id":{"type":"integer","description":"Required for component_type flow, rejected otherwise."}}},"BusinessAgentUiSkill":{"allOf":[{"$ref":"#/components/schemas/BusinessAgentUiSkillInput"},{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"created_at":{"type":"integer","description":"Unix seconds."},"updated_at":{"type":"integer","description":"Unix seconds."}}}]},"BusinessAgentApiKeyConfig":{"type":"object","description":"Where the connector injects the API key on each call.","properties":{"headers":{"$ref":"#/components/schemas/BusinessAgentApiKeyParams"},"query_params":{"$ref":"#/components/schemas/BusinessAgentApiKeyParams"},"body_params":{"$ref":"#/components/schemas/BusinessAgentApiKeyParams"}}},"BusinessAgentApiKeyParams":{"type":"array","items":{"type":"object","required":["field_name","value"],"properties":{"field_name":{"type":"string"},"value":{"type":"string"},"prefix":{"type":"string"}}}},"BusinessAgentOAuthClientCredentials":{"type":"object","required":["token_url","client_id","client_secret"],"properties":{"token_url":{"type":"string","format":"uri"},"scopes_to_request":{"type":"array","items":{"type":"string"}},"token_request_content_type":{"type":"string","example":"application/x-www-form-urlencoded"},"client_id":{"type":"string"},"client_secret":{"type":"string"}}},"BusinessAgentConnectorInput":{"type":"object","required":["name","base_url","auth_type"],"properties":{"name":{"type":"string","description":"Unique per number."},"description":{"type":"string","description":"Tell the agent what the service provides."},"base_url":{"type":"string","format":"uri","description":"Public HTTPS URL reachable from Meta."},"connector_protocol":{"type":"string","example":"HTTP"},"auth_type":{"type":"string","enum":["OAUTH2_CLIENT_CREDENTIALS","API_KEY","NONE"]},"auth_config":{"type":"object","properties":{"oauth2_client_credentials":{"$ref":"#/components/schemas/BusinessAgentOAuthClientCredentials"},"api_key":{"$ref":"#/components/schemas/BusinessAgentApiKeyConfig"}}},"user_auth_injection_config":{"type":"object","required":["location","field_name"],"properties":{"location":{"type":"string","example":"headers"},"field_name":{"type":"string"},"prefix":{"type":"string"}}},"requires_certificate":{"type":"boolean"}}},"BusinessAgentConnector":{"allOf":[{"$ref":"#/components/schemas/BusinessAgentConnectorInput"},{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"mcp_tool_sync":{"type":"object","additionalProperties":true},"mtls_config":{"type":"object","additionalProperties":true},"connection_status":{"type":"object","properties":{"status":{"type":"string","description":"ACTIVE, PENDING_OAUTH, EXPIRED or ERROR."},"error_message":{"type":"string"}}}}}]},"BusinessAgentConnectorToolInput":{"type":"object","required":["name","description","request_definition"],"properties":{"name":{"type":"string"},"description":{"type":"string","description":"When and how the agent should use the operation."},"request_definition":{"type":"object","additionalProperties":true,"description":"Meta request definition: method, path, path_parameters, query_parameters, headers and a typed body schema (content_type, params, required)."},"user_auth_required":{"type":"boolean"},"user_auth_action_config":{"type":"object","additionalProperties":true},"transformation_spec":{"type":"object","additionalProperties":true}}},"BusinessAgentConnectorTool":{"allOf":[{"$ref":"#/components/schemas/BusinessAgentConnectorToolInput"},{"type":"object","required":["id"],"properties":{"id":{"type":"string"}}}]},"BusinessAgentBudget":{"type":"object","required":["unit_type","time_window","max_budget"],"properties":{"budget_id":{"type":"string","description":"Pass it back to edit an existing budget; omit to add one."},"unit_type":{"type":"string","enum":["token","ai_turn"],"description":"Tokens count across the Business Manager, AI turns per conversation."},"time_window":{"type":"string","enum":["one_day","seven_days","fourteen_days","thirty_days"],"description":"Rolling window in the WABA timezone."},"max_budget":{"type":"integer","minimum":1}}},"BusinessAgentTestMessageResponse":{"type":"object","required":["message_id","agent_response","conversation_id"],"properties":{"message_id":{"type":"string"},"agent_response":{"type":"string"},"conversation_id":{"type":"string","description":"Pass it back as conversationId to continue the thread."},"timestamp":{"type":"integer","description":"Unix seconds."},"handoff_reason":{"type":"string"},"no_response_reason":{"type":"string"},"quick_replies":{"type":"array","items":{"type":"string"}},"product_variant_ids":{"type":"array","items":{"type":"string"}}}},"BusinessAgentEventStatus":{"type":"object","required":["status","event_type","created_at","updated_at"],"properties":{"status":{"type":"string","enum":["request_received","processing","sent","failed","skipped","success"]},"event_type":{"type":"string"},"error_message":{"type":"string"},"skipped_reason":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"StorePixelInstall":{"type":"object","description":"A tracking tag's install on a connected store: a Shopify web pixel, a Custom HTML widget on a WordPress site, the Zernio embedded script on a Wix site, or the Zernio custom code script on a Webflow site. Fields marked with a platform are present only for it.","properties":{"storeAccountId":{"type":"string"},"platform":{"type":"string","enum":["shopify","wordpress","wix","webflow"],"description":"The store platform."},"tagPlatform":{"type":"string","description":"Platform of the tag this install is about (e.g. `metaads`)."},"siteTagId":{"type":"string","description":"The id the tag carries on the site (see `TrackingTag.siteTagId`)."},"installed":{"type":"boolean","description":"Shopify, Wix and Webflow: this tag is the one the store fires for its platform. WordPress: the Zernio widget for this tag is in an active widget area with its script intact."},"shopDomain":{"type":"string","example":"acme.myshopify.com","description":"Shopify only."},"installedTagId":{"type":["string","null"],"description":"Shopify, Wix and Webflow only: the tag of the same platform the store fires now (may be a different tag), or null."},"tags":{"type":"array","description":"GET only on WordPress, always on Shopify, Wix and Webflow: every Zernio tag on the store, all platforms.","items":{"type":"object","properties":{"platform":{"type":"string"},"siteTagId":{"type":"string"},"widgetId":{"type":"string","description":"WordPress only."},"sidebarId":{"type":"string","description":"WordPress only."},"active":{"type":"boolean","description":"WordPress only: false when the widget sits outside an active widget area."}}}},"webPixelId":{"type":["string","null"],"description":"Shopify only: web pixel id, or null when nothing is installed."},"siteUrl":{"type":["string","null"],"description":"WordPress, Wix and Webflow only. Null on a Wix site that was never published."},"publishRequired":{"type":"boolean","description":"Webflow only, always true: the change reaches the live site on its next publish."},"method":{"type":"string","enum":["wordpress_widget"],"description":"WordPress only."},"widgetId":{"type":["string","null"],"description":"WordPress only: widget id, e.g. `custom_html-3`."},"sidebarId":{"type":["string","null"],"description":"WordPress only: widget area holding the widget."}}},"TrackingTagInstallBlockedReason":{"type":"string","enum":["insufficient_permissions","scripts_stripped","wordpress_com_plan","no_widget_areas","widgets_api_unavailable"],"description":"Why a pixel cannot be installed on a WordPress site."},"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`).\n\nThe shape is platform-neutral so other platforms (Pinterest Tag, LinkedIn Insight Tag, etc.) can be added without changing the contract. Platform-specific fields are absent where a platform has no equivalent.\n\nReturned by `listTrackingTags`, `createTrackingTag`, `getTrackingTag`, and `updateTrackingTag`.\n","required":["id","name","platform","kind","status"],"properties":{"id":{"type":"string","description":"Platform-native tag id, the `{tagId}` of the per-tag routes. Meta: numeric pixel id, as a string. OpenAI: the pixel resource id. Google Ads: the 10-digit customer id (one Google tag per account)."},"siteTagId":{"type":"string","description":"The id the on-site code carries. Equals `id` on Meta; differs on platforms with separate API and site ids (OpenAI `pixel_id`, Google `AW-...` conversion id, the manager's under cross-account conversion tracking)."},"events":{"type":"array","description":"Platforms where each conversion is its own object: the tag's conversion events, with the id a site sends for each.","items":{"$ref":"#/components/schemas/TrackingTagEvent"}},"name":{"type":"string"},"platform":{"type":"string","enum":["metaads","openaiads","tiktokads","googleads","xads","linkedinads","pinterestads","whopads"]},"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 `<script>` snippet to install on the site, including\nthe page-view call. Populated by `getTrackingTag`, omitted from the\nlist view.\n"},"lastFiredTime":{"type":["integer","null"],"description":"Unix seconds of the last event the tag received, or `null` if it\nnever fired. The practical \"is it installed and working\" signal.\n"},"isUnavailable":{"type":"boolean","description":"Whether the tag is in a broken/unavailable state (Meta `is_unavailable`)."},"installed":{"type":"boolean","description":"Convenience flag derived from `lastFiredTime`: has the tag ever fired."},"creationTime":{"type":"integer","description":"Unix seconds the tag was created."},"automaticMatchingFields":{"type":"array","items":{"type":"string","enum":["em","ph","fn","ln","ge","db","ct","st","zp","country","external_id"]},"description":"Customer data the tag matches automatically, where the platform reports it (Pinterest automatic enhanced match)."},"ownerBusinessId":{"type":["string","null"],"description":"Business Manager id that owns the tag, or `null` when the tag lives\non a personal (non-BM) ad account. Such tags can't be shared with\nother ad accounts.\n"},"ownerAdAccountId":{"type":"string","description":"Ad account id (`act_...`) that owns the tag, when reported."},"autoTagging":{"type":"boolean","description":"Google Ads: whether gclid auto-tagging is on for the ad account (needed to attribute conversions to clicks)."}}},"TrackingTagEvent":{"type":"object","description":"A conversion event tied to a tracking tag (Google conversion action, LinkedIn conversion rule, X web event tag, OpenAI event setting, TikTok pixel event, Meta custom conversion).","required":["id","name"],"properties":{"id":{"type":"string","description":"Platform-native event id, the `{eventId}` of the per-event routes."},"name":{"type":"string"},"type":{"type":"string","description":"Platform event type or category."},"siteEvent":{"type":"string","enum":["page_view","view_content","add_to_cart","search","initiate_checkout","add_payment_info","purchase"],"description":"The neutral site event this conversion is fired for, when it maps to one."},"siteEventId":{"type":"string","description":"What the site sends to fire this event (Google conversion label, LinkedIn conversion rule id, X `tw-` event id)."},"status":{"type":"string"},"defaultValue":{"type":"number"},"currency":{"type":"string"},"clickWindowDays":{"type":"integer"},"viewWindowDays":{"type":"integer"},"urlContains":{"type":"string","description":"Fires only on pages whose URL contains this text (case-insensitive)."},"alwaysUseDefaultValue":{"type":"boolean","description":"`defaultValue` is recorded even when the conversion sends its own value."},"primary":{"type":"boolean","description":"Primary conversions count toward bidding and the Conversions column; secondary ones are observation only (Google `primary_for_goal`)."},"countingType":{"type":"string","enum":["one","every"],"description":"`one` counts at most one conversion per ad interaction (leads), `every` counts each (purchases)."}}},"TrackingTagEventInput":{"type":"object","description":"Conversion event fields. Each platform stores a subset; a field it does not store answers 400 naming the supported ones.","properties":{"adAccountId":{"type":"string","description":"Scopes the lookup on platforms whose tag ids live inside an ad account."},"name":{"type":"string","minLength":1,"maxLength":200},"type":{"type":"string","description":"The platform's own event type enum value (e.g. `PURCHASE`)."},"siteEvent":{"type":"string","enum":["page_view","view_content","add_to_cart","search","initiate_checkout","add_payment_info","purchase"],"description":"Neutral alternative to `type`, mapped to the platform's closest type."},"enabled":{"type":"boolean"},"defaultValue":{"type":"number","minimum":0},"currency":{"type":"string","description":"ISO 4217 code."},"clickWindowDays":{"type":"integer","minimum":1,"maximum":365},"viewWindowDays":{"type":"integer","minimum":0,"maximum":365},"urlContains":{"type":"string","minLength":1,"maxLength":500,"description":"Fire only on pages whose URL contains this text (case-insensitive)."}}},"TrackingTagUser":{"type":"object","description":"A person or system user of the owning business with access to a tracking tag.","required":["id","tasks"],"properties":{"id":{"type":"string","description":"Business-scoped user id (as listed by GET /v1/ads/businesses/users)."},"name":{"type":"string"},"tasks":{"type":"array","items":{"type":"string"},"description":"Platform permission names (Meta: `AA_ANALYZE`, `ADVERTISE`, `ANALYZE`, `EDIT`, `UPLOAD`)."}}},"TrackingTagPartner":{"type":"object","description":"Another business a tracking tag is shared with.","required":["id"],"properties":{"id":{"type":"string","description":"Partner business id."},"name":{"type":"string"}}},"TrackingTagDiagnostic":{"type":"object","description":"One health check the platform runs on a tracking tag.","required":["key","title","result"],"properties":{"key":{"type":"string","description":"Platform check id (Meta: e.g. `pixel_missing_param_in_events`)."},"title":{"type":"string"},"description":{"type":"string"},"result":{"type":"string","description":"The platform verdict (Meta: `passed`, `failed`, `warning`)."},"actionUrl":{"type":"string","description":"Where to fix it in the platform UI (Meta: Events Manager)."},"alwaysUseDefaultValue":{"type":"boolean","description":"Record `defaultValue` even when the conversion sends its own value."},"primary":{"type":"boolean","description":"Primary (counts toward bidding) or secondary (observation only)."},"countingType":{"type":"string","enum":["one","every"],"description":"`one` = one conversion per ad interaction, `every` = each conversion."}}},"SharedAdAccount":{"type":"object","description":"An ad account a tracking tag is shared with (Meta `shared_accounts` edge).","required":["id"],"properties":{"id":{"type":"string","description":"Ad account id, in `act_<digits>` form."},"name":{"type":"string"},"businessId":{"type":"string","description":"Business Manager id that owns the ad account, when reported."}}}}},"webhooks":{"post.scheduled":{"post":{"operationId":"onPostScheduled","summary":"Post scheduled event","description":"Fired whenever a post enters the scheduled state: created with a schedule, added to a queue, a draft promoted to scheduled or queued, a failed or partial post retried, or a recycled clone created. Not fired when an already-scheduled post is edited or rescheduled.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadPost"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"post.published":{"post":{"operationId":"onPostPublished","summary":"Post published event","description":"Fired when a post is successfully published.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadPost"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"post.failed":{"post":{"operationId":"onPostFailed","summary":"Post failed event","description":"Fired when a post fails to publish on all target platforms.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadPost"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"post.partial":{"post":{"operationId":"onPostPartial","summary":"Post partial event","description":"Fired when a post publishes on some platforms and fails on others.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadPost"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"post.cancelled":{"post":{"operationId":"onPostCancelled","summary":"Post cancelled event","description":"Fired when a scheduled post is cancelled because its account was disconnected and nothing published. Not sent when a post is deleted.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadPost"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"post.recycled":{"post":{"operationId":"onPostRecycled","summary":"Post recycled event","description":"Fired when a post is recycled (cloned and re-scheduled for publishing). The new clone also fires a post.scheduled event.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadPost"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"post.platform.published":{"post":{"operationId":"onPostPlatformPublished","summary":"Post platform published event","description":"Fired once per platform target inside a post, as soon as that platform finishes publishing successfully.\n\nIt does NOT wait for the post-level rollup, so incremental UIs get notified immediately, even while other platforms on the same post are still processing.\n\n- The envelope event (`post.published` / `post.partial`) fires separately, AFTER all platforms have terminated.\n- If a target later fails background reconciliation (e.g. a Facebook video Meta accepted but never actually published), `post.platform.failed` fires for the same target afterward.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadPostPlatform"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"post.platform.failed":{"post":{"operationId":"onPostPlatformFailed","summary":"Post platform failed event","description":"Fired once per platform target inside a post when that platform fails permanently.\n\n- Temporary/retryable failures do NOT fire this event, so retry loops stay quiet.\n- The envelope event (`post.failed` / `post.partial`) fires separately, AFTER all platforms have terminated.\n- It can fire for a target that already emitted `post.platform.published`, if background reconciliation later finds the publish never actually completed.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadPostPlatform"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"post.platform.deleted":{"post":{"operationId":"onPostPlatformDeleted","summary":"Post platform deleted event","description":"Fired when Zernio's background sync detects that a platform target published through Zernio was later deleted on the platform (e.g. the user deleted the Instagram post natively).\n\n- Detection is poll-driven (~hourly), not real-time, and fires once per platform target.\n- `platform.deletedAt` carries the detection time.\n- Detection is listing-based: a false positive self-heals in Zernio's data when the post reappears, but the event is not retracted.\n- Coverage is bounded to the posts the platform listing returns.\n- Detection diffs against the posts a prior sync already indexed. An account with no indexed post can never emit this event, no matter how the subscription is configured.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadPostPlatform"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"post.tiktok.url_resolved":{"post":{"operationId":"onPostTikTokUrlResolved","summary":"TikTok post URL resolved event","description":"Fired when an already-published TikTok platform entry gets its public URL backfilled.\n\nTikTok exposes the numeric video id asynchronously (often minutes after PUBLISH_COMPLETE), so the terminal events can carry an empty `publishedUrl` for TikTok. This event delivers `platform.publishedUrl` and the resolved `platform.platformPostId` once available.\n\n- Fires at most once per platform target.\n- Never fires for drafts or private posts (no public URL exists).\n- The payload shape is identical to `post.platform.published`.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadPostPlatform"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"account.connected":{"post":{"operationId":"onAccountConnected","summary":"Account connected event","description":"Fired when a account is successfully connected.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAccountConnected"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"account.rate_limited":{"post":{"operationId":"onAccountRateLimited","summary":"Mailbox sending cooldown started","description":"Fired when a Google or Microsoft mailbox enters a sending cooldown (same body to more than 50 recipients in an hour, or a later trigger). Sends answer 429 until `account.resetsAt`.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAccountRateLimited"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"calendar.event.created":{"post":{"operationId":"onCalendarEventCreated","summary":"Calendar event created","description":"A new event appeared on a connected Microsoft calendar (push, seconds after the change).","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCalendarEvent"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"calendar.event.updated":{"post":{"operationId":"onCalendarEventUpdated","summary":"Calendar event updated","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCalendarEvent"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"calendar.event.deleted":{"post":{"operationId":"onCalendarEventDeleted","summary":"Calendar event deleted","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCalendarEvent"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"file.created":{"post":{"operationId":"onFileCreated","summary":"File created","description":"A file or folder appeared in a connected Drive or OneDrive (push, seconds after the change).","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadFile"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"file.updated":{"post":{"operationId":"onFileUpdated","summary":"File updated","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadFile"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"file.picked":{"post":{"operationId":"onFilePicked","summary":"Files picked","description":"The user finished a hosted picker session (`POST /v1/files/picker-sessions`) and picked at least one file. The app can now open those files. Not sent on cancel.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadFilePicked"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"file.deleted":{"post":{"operationId":"onFileDeleted","summary":"File deleted","description":"The item was trashed or removed on the provider.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadFile"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"contact.updated":{"post":{"operationId":"onContactUpdated","summary":"Contact updated","description":"A provider contacts sync (Google Contacts, Outlook) or a WhatsApp coexistence address-book change created or changed a contact.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadContact"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"contact.deleted":{"post":{"operationId":"onContactDeleted","summary":"Contact deleted","description":"The provider contact was deleted; its email channel is removed, the contact row stays when other channels remain.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadContact"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"account.disconnected":{"post":{"operationId":"onAccountDisconnected","summary":"Account disconnected event","description":"Fired when a connected account becomes disconnected: deactivated after an auth error, or flagged as needing reconnection (`needsReconnection: true` on GET /v1/accounts).\n\nA flagged account that is later deactivated sends it again with the new reason. A deactivated account does not send it again until it is reconnected.\n\nRequests that need the account answer 409 `account_disconnected` until then. A webhook only receives the events it lists, so subscribe to this one explicitly.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAccountDisconnected"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"account.permissions_changed":{"post":{"operationId":"onAccountPermissionsChanged","summary":"Account permissions changed event","description":"Fired when a publish on an account connected through your own OAuth app fails for a missing permission. The account stays connected; only the missing area stops working until the permission is granted and the account reconnected.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAccountPermissionsChanged"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"account.ads.initial_sync_completed":{"post":{"operationId":"onAccountAdsInitialSyncCompleted","summary":"Ads initial sync completed event","description":"Fired once per ads-enabled account when the initial sync (ad-account\ndiscovery + 90-day historical ad backfill) completes. The `sync` block\nreports whether the backfill succeeded and how many ads were synced.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAccountAdsInitialSyncCompleted"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"account.ads.sync_failed":{"post":{"operationId":"onAccountAdsSyncFailed","summary":"Ads sync failed event","description":"Fired once per ad account when its ads stop syncing (no successful sync for 24 hours,\nor every live ad at the retry cap). Checked hourly. Metrics for the ad account are stale\nuntil `account.ads.sync_recovered` fires for it.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAccountAdsSyncFailed"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"account.ads.sync_recovered":{"post":{"operationId":"onAccountAdsSyncRecovered","summary":"Ads sync recovered event","description":"Fired once when an ad account previously reported by `account.ads.sync_failed` syncs\nsuccessfully again. Checked hourly.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAccountAdsSyncRecovered"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"analytics.synced":{"post":{"operationId":"onAnalyticsSynced","summary":"Analytics synced event","description":"Fired once per connected account each time its analytics sync cycle completes\nsuccessfully. Poll-driven (roughly hourly per account), not real-time, and never\nfired for a skipped or failed cycle.\n\nA trigger, not a transport: the payload carries no metrics and no cursor. On\nreceipt, call `GET /v1/analytics/delta` with your own last `nextCursor` to read\nevery post whose analytics changed, across every account, in one paginated\nstream instead of polling analytics once per account.\n\nThe feed holds back its most recent few seconds of writes, so a read issued the\ninstant this event lands often returns an empty page for that account. Poll again\nwith the same cursor rather than reading an empty page as \"nothing changed\".\n\nHigh volume (roughly one delivery per connected account per hour). Subscribe to\nit on a dedicated webhook endpoint: a subscription's consecutive-failure count is\nshared across all of its events, so an outage while this event is flowing can\nsuppress the low-volume publishing events on the same subscription.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAnalyticsSynced"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"post.tracking_completed":{"post":{"operationId":"onPostTrackingCompleted","summary":"Post tracking completed event","description":"Fired once when a post's tracking window ends and its final analytics read has\nrun. `final` carries the closing metrics, or null when none could be read, and\n`window.completionReason` is `final_read`, `unreachable` or `post_deleted`.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadPostTrackingCompleted"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"post.authenticity_changed":{"post":{"operationId":"onPostAuthenticityChanged","summary":"Post authenticity changed event","description":"Fired when a tracked post's authenticity score crosses 40 in either direction.\nCarries the new and previous score, confidence and reasons. A first score never fires it.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadPostAuthenticityChanged"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"message.received":{"post":{"operationId":"onMessageReceived","summary":"Message received event","description":"Fired when a new inbox message is received.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadMessage"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"conversation.control_changed":{"post":{"operationId":"onConversationControlChanged","summary":"Conversation control changed event","description":"Fired on Meta's handover protocol (`messaging_handovers`), when control of a conversation thread changes.\n\nWhatsApp: control moves between Meta Business Agent and your app, or the agent is first seen answering a thread. While `control.owner` is `ai_agent`:\n\n- Inbound messages arrive on `message.received` with `metadata.standby: true`.\n- The agent's replies arrive on `message.sent` with `source: meta_business_agent`.\n- Sending any message takes control back.\n\nFacebook and Instagram: another app passed you the thread (`owner: app`), or took or received it (`owner: other`, with `ownerAppId`). While you are not the owner:\n\n- Inbound messages arrive with `metadata.standby: true`.\n- No automation runs.\n- Sends fail with `not_thread_owner`.\n\nChange control with `POST /v1/inbox/conversations/{conversationId}/thread-control`. `take` and `request` answer 400 `platform_not_supported` on Instagram Login connections.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadConversationControlChanged"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"conversation.started":{"post":{"operationId":"onConversationStarted","summary":"Conversation started event","description":"Fired once when a new conversation begins between one of your connected accounts and a\ncontact, in either direction. Works across every DM platform (Instagram, Messenger/Facebook,\nTelegram, WhatsApp, X, Reddit, Bluesky, TikTok). Naturally deduped: a given conversation\nonly fires this event the very first time it appears.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadConversationStarted"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"call.received":{"post":{"operationId":"onCallReceived","summary":"Call received event","description":"Fired when a WhatsApp Business Call connects. For inbound (UIC) calls\nthe event fires at the moment our Telnyx trunk bridges the consumer\nleg to the customer&apos;s forward-to destination; for outbound (BIC)\ncalls it fires immediately after Meta accepts the connect. Branch on\n`call.direction` to distinguish.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCallReceived"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"call.ended":{"post":{"operationId":"onCallEnded","summary":"Call ended event","description":"Fired on call hangup with the duration and a zero-markup billing\nbreakdown (Meta cost, Telnyx cost, recording surcharge, total).\nCosts are pass-through; no margin is applied.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCallEnded"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"call.failed":{"post":{"operationId":"onCallFailed","summary":"Call failed event","description":"Fired when a call setup or in-progress call fails (Meta rejected the\nconnect, Telnyx returned an error, etc.). Payload carries the\nupstream error code and message.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCallFailed"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"call.permission_request":{"post":{"operationId":"onCallPermissionRequest","summary":"Call permission request reply event","description":"Fired when a consumer replies to a `call_permission_request`\ninteractive message (or its marketing-template variant). Carries\nthe response (`accept` / `reject`), whether the grant is permanent,\nand the expiration timestamp when it is temporary.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCallPermissionRequest"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"message.sent":{"post":{"operationId":"onMessageSent","summary":"Message sent event","description":"Fired when a message is sent via the API, or from the WhatsApp Business app on Coexistence numbers.\n\nSends that carry platform-specific context deliver it under `metadata`. A quote-reply sent through the API arrives with `metadata.quotedMessageId`, so mirroring CRMs can thread it without a lookup.\n\nWhich surfaces carry that reference is documented on `WebhookPayloadMessageSent.metadata.quotedMessageId`. A quote-reply sent from the WhatsApp Business or Instagram app is not one of them.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadMessageSent"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"message.edited":{"post":{"operationId":"onMessageEdited","summary":"Message edited event","description":"Fired when a sender edits a previously-sent message. Supported on\nInstagram, Facebook Messenger, Telegram, and WhatsApp. The payload\nincludes the full editHistory so consumers can show prior versions.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadMessageEdited"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"message.deleted":{"post":{"operationId":"onMessageDeleted","summary":"Message deleted event","description":"Fired when a sender deletes (unsends) a message.\n\n- Instagram: incoming unsend.\n- WhatsApp, outgoing: a message the business deleted (via the Cloud API, or from the WhatsApp Business app on a Coexistence number).\n- WhatsApp, incoming: a message the customer deleted.\n\nRead `message.direction` to tell the two directions apart.\n\nThe payload retains the pre-delete text and attachments so API consumers can access the original content for moderation or compliance. The Zernio dashboard UI hides it.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadMessageDeleted"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"message.delivered":{"post":{"operationId":"onMessageDelivered","summary":"Message delivered event","description":"Fired when an outgoing message is delivered to the recipient.\nSupported on WhatsApp and Facebook Messenger.\nOn WhatsApp, `pricing` and `billingConversation` carry Meta's billing context for\nthe message (also on `message.sent`, `message.read` and `message.failed`).\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadMessageDeliveryStatus"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"message.read":{"post":{"operationId":"onMessageRead","summary":"Message read event","description":"Fired when an outgoing message is read by the recipient. Supported on\nWhatsApp, Facebook Messenger, Instagram, and RCS.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadMessageDeliveryStatus"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"message.played":{"post":{"operationId":"onMessagePlayed","summary":"Message played event","description":"Fires the first time the recipient plays a voice message you sent on WhatsApp.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadMessageDeliveryStatus"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"message.failed":{"post":{"operationId":"onMessageFailed","summary":"Message delivery failed event","description":"Fired when an outgoing message fails to deliver. Currently only emitted\nfor WhatsApp (other platforms don't expose per-message failure via\nwebhook). The payload error object contains code, title, and\nmessage from the platform.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadMessageDeliveryStatus"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"reaction.received":{"post":{"operationId":"onReactionReceived","summary":"Reaction received event","description":"Fired when a participant adds or removes an emoji reaction on a message. Requires the Inbox add-on.\n\nSupported on WhatsApp, Telegram, Slack, Instagram, Facebook Messenger and TikTok. It is distinct from message.received, so a reaction (e.g. a thumbs-up) is not mistaken for an inbound message.\n\n- `reaction.action` is `added` or `removed`.\n- On WhatsApp and Meta removals, the platform does not report which emoji was removed, so `reaction.emoji` may be an empty string.\n- On TikTok, a like or emoji reaction on a DM arrives only as this event (never as an empty message.received), with `reaction.platformMessageId` set to the TikTok id of the liked message.\n- Instagram and Facebook accounts connected before reactions shipped only emit this event after their webhook subscription is refreshed. Reconnect the account if reactions never arrive.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadReaction"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"referral.received":{"post":{"operationId":"onReferralReceived","summary":"Referral received event","description":"Fired when someone opens an EXISTING Instagram or Messenger thread through an attributable entry point, which Meta delivers as a standalone referral with no message attached. Requires the Inbox add-on.\n\nEntry points:\n\n- An ig.me / m.me link with a `ref` parameter.\n- (Messenger) A returning Click-to-Message ad click.\n\nA referral that rides an inbound message (first message of a thread, icebreaker taps, returning ad clicks on Instagram) arrives on `message.received` under `metadata.referral` instead. The two never fire for the same click.\n\nThe first referral captured on a conversation is also persisted on it (see `metadata` on `GET /v1/inbox/conversations`).\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadReferral"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"comment.received":{"post":{"operationId":"onCommentReceived","summary":"Comment received event","description":"Fired when a new comment is received on a tracked post.\n\n- Delivered for Instagram, Facebook, Threads, YouTube, LinkedIn, Bluesky, Reddit and TikTok.\n- X/Twitter does NOT fire this event.\n- Instagram, Facebook and TikTok arrive in real time from the platform's own webhook. The rest are poll-driven, so delivery is not instant.\n- TikTok needs an account connected through the TikTok for Business app.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadComment"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"review.new":{"post":{"operationId":"onReviewNew","summary":"Review new event","description":"Fired when a new review is posted on a connected account. Currently supported\nfor Google Business Profile (real-time via Pub/Sub). Requires the Inbox add-on.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadReviewNew"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"review.updated":{"post":{"operationId":"onReviewUpdated","summary":"Review updated event","description":"Fired when a Google Business Profile reviewer edits their review text or rating, or when a reply is added, edited or removed. Payload shape matches review.new. Requires the Inbox add-on.\n\nA reply posted through POST /v1/inbox/reviews/{reviewId}/reply fires immediately. The periodic check then reports it again with the full review payload, so expect a second delivery.\n\nReplies written or removed in Google's own interface, and replies removed through the API, are reported by the periodic check.\n\nFor replies written in Google, that is usually within 6 hours for reviews updated in the last 30 days, and usually within about 7 days for older ones. Only locations covered by a webhook subscribed to review.updated are checked. A removed reply fires with hasReply false.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadReviewUpdated"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"review.deleted":{"post":{"operationId":"onReviewDeleted","summary":"Review deleted event","description":"Google Business Profile stopped returning this review, for example after Google's spam filter removed it. Detected by polling, it usually fires 6 to 12 hours after the review disappears.\n\n- Opt-in: only locations covered by a webhook subscribed to review.deleted or review.restored are checked.\n- If the review comes back, review.restored fires. A review Google hides and later restores produces review.deleted and then review.restored.\n- A review.updated can arrive for a review reported by review.deleted. The next check restores it.\n- It may arrive for a review id you never received review.new for. Ignore ids you do not know.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadReviewDeleted"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"review.restored":{"post":{"operationId":"onReviewRestored","summary":"Review restored event","description":"A review reported by review.deleted is returned by Google again. Same payload as review.new.\nRequires the Inbox add-on.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadReviewRestored"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"post.external.created":{"post":{"operationId":"onPostExternalCreated","summary":"External post created event","description":"Fired when Zernio's background sync detects a natively-authored post\n(created outside Zernio, e.g. a Google Business Profile localPost made in\nthe Google UI) for the first time. Poll-driven (~hourly), not real-time.\n`post.source` is always \"external\".\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadExternalPost"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"post.external.updated":{"post":{"operationId":"onPostExternalUpdated","summary":"External post updated event","description":"Fired when a tracked native post's text or media changed on the platform.\nDetected by comparing text/media structure and, where available, the\nplatform's own edit timestamp; a media-URL-only refresh does not fire this.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadExternalPost"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"post.external.deleted":{"post":{"operationId":"onPostExternalDeleted","summary":"External post deleted event","description":"Fired when a tracked native post is detected as removed from the platform.\n\n- `post.deletedAt` carries the detection time.\n- Coverage is bounded to the most recent posts the platform listing returns.\n- Detection diffs against the posts a prior sync already indexed. An account with no indexed post can never emit this event, no matter how the subscription is configured.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadExternalPost"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"lead.received":{"post":{"operationId":"onLeadReceived","summary":"Lead received event","description":"Fired when a new lead is submitted against a Meta Lead Gen (Instant) Form\nand ingested via the Page `leadgen` webhook. `lead.fields` is the\nquestion-key to answer map; `lead.formId` / `lead.adId` give provenance.\nRequires the Ads add-on.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadLead"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"ad.status_changed":{"post":{"operationId":"onAdStatusChanged","summary":"Ad status changed event","description":"Fired when a campaign, ad set, or ad on a connected ad platform changes status. Currently emitted only for Meta (`metaads`).\n\nIt subscribes to two Meta `ad_account` webhook fields:\n\n- `in_process_ad_objects`: the ad object finished processing and exited the `IN_PROCESS` state. `status.raw` carries Meta's `status_name` (e.g. `ACTIVE`, `PAUSED`, `ARCHIVED`, `DELETED`).\n- `with_issues_ad_objects`: the ad object entered the `WITH_ISSUES` state. `status.raw` is `WITH_ISSUES` and the `error` block is populated from Meta's `error_code` / `error_summary` / `error_message`.\n\n`adObject.level` mirrors Meta's `level` and is one of `CAMPAIGN`, `AD_SET`, or `AD`. Creative-level events are not forwarded.\n\nBranch on `status.raw` to handle each transition. Use `error.code` (when present) as the stable discriminator, since `error.summary` and `error.message` are localized to the ad-account owner's Meta locale.\n\nThe `error` block is optional:\n\n- It is present on most `WITH_ISSUES` events but can be absent (Meta does not always include diagnostics).\n- It is never present on any other status.\n- Always null-check `error` before reading `error.code`.\n\n**Fan-out:** matching is keyed on `adObject.platformAdAccountId`. When multiple connected Zernio `metaads` accounts are linked to the same Meta ad account, each receives its own delivery.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAdStatusChanged"},"examples":{"inProcessActive":{"summary":"in_process_ad_objects → ACTIVE (ad approved)","value":{"id":"01J7K3P4N5Q6R7S8T9V0W1X2Y3","event":"ad.status_changed","account":{"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","profileId":"65c8f7e2a1b3c4d5e6f7a800","platform":"metaads","username":"acme-ads","displayName":"Acme Ads"},"adObject":{"level":"AD","platformId":"120244894077860689","platformAdAccountId":"act_2129800524463520"},"status":{"raw":"ACTIVE"},"timestamp":"2026-05-05T15:25:27.944Z"}},"withIssuesError":{"summary":"with_issues_ad_objects → WITH_ISSUES (error populated)","value":{"id":"01J7K3P4N5Q6R7S8T9V0W1X2Y4","event":"ad.status_changed","account":{"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","profileId":"65c8f7e2a1b3c4d5e6f7a800","platform":"metaads","username":"acme-ads","displayName":"Acme Ads"},"adObject":{"level":"AD","platformId":"120244560555500043","platformAdAccountId":"act_587875401826220"},"status":{"raw":"WITH_ISSUES"},"error":{"code":"2643001","summary":"Ad Processing Error","message":"Ad Processing Error: We are having trouble processing your request. To resolve the issue, please try to publish again."},"timestamp":"2026-05-08T04:22:35.821Z"}},"inProcessWithIssues":{"summary":"in_process_ad_objects → WITH_ISSUES (no error block)","value":{"id":"01J7K3P4N5Q6R7S8T9V0W1X2Y5","event":"ad.status_changed","account":{"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","profileId":"65c8f7e2a1b3c4d5e6f7a800","platform":"metaads","username":"acme-ads"},"adObject":{"level":"AD","platformId":"120244560555500043","platformAdAccountId":"act_587875401826220"},"status":{"raw":"WITH_ISSUES"},"timestamp":"2026-05-08T04:22:35.821Z"}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"ad.created":{"post":{"operationId":"onAdCreated","summary":"Ad created event","description":"Fired when an ad is created through Zernio (`source: \"zernio\"`) or detected by the sync (`source: \"platform\"`).\nNever for history loaded when an account connects, nor for ads older than 7 days. See `WebhookPayloadAdCreated`.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAdCreated"},"examples":{"sample":{"summary":"TikTok ad created","value":{"id":"01J7K3P4N5Q6R7S8T9V0W1X2Z2","event":"ad.created","account":{"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","profileId":"65c8f7e2a1b3c4d5e6f7a800","platform":"tiktokads","username":"acme-ads","displayName":"Acme Ads"},"adObject":{"level":"AD","platformId":"1870423675882786","platformAdAccountId":"7505325609036365841","adId":"65c8f7e2a1b3c4d5e6f7a8c1","name":"Spring promo","campaign":{"platformCampaignId":"1870423600000001","name":"Spring campaign"},"adSet":{"platformAdSetId":"1870423600000002","name":"Spring audience"}},"source":"zernio","timestamp":"2026-10-22T09:12:03.120Z"}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"ad.updated":{"post":{"operationId":"onAdUpdated","summary":"Ad updated event","description":"Fired when an ad is edited through Zernio (`source: \"zernio\"`) or when the sync detects an edit made outside Zernio (`source: \"platform\"`).\n`changes` lists the edited fields. See `WebhookPayloadAdUpdated`.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAdUpdated"},"examples":{"sample":{"summary":"Ad renamed and creative replaced","value":{"id":"01J7K3P4N5Q6R7S8T9V0W1X2Z5","event":"ad.updated","account":{"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","profileId":"65c8f7e2a1b3c4d5e6f7a800","platform":"tiktokads","username":"acme-ads","displayName":"Acme Ads"},"adObject":{"level":"AD","platformId":"1870423675882786","platformAdAccountId":"7505325609036365841","adId":"65c8f7e2a1b3c4d5e6f7a8c1","name":"Spring promo","campaign":{"platformCampaignId":"1870423600000001","name":"Spring campaign"},"adSet":{"platformAdSetId":"1870423600000002","name":"Spring audience"}},"changes":["name","creative"],"source":"zernio","timestamp":"2026-10-22T09:12:03.120Z"}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"campaign.created":{"post":{"operationId":"onCampaignCreated","summary":"Campaign created event","description":"Fired when a campaign is created through Zernio (`source: \"zernio\"`) or detected by the sync (`source: \"platform\"`).\nNever for history loaded when an account connects, nor for campaigns older than 7 days. See `WebhookPayloadCampaignCreated`.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCampaignCreated"},"examples":{"sample":{"summary":"TikTok campaign created","value":{"id":"01J7K3P4N5Q6R7S8T9V0W1X2Z3","event":"campaign.created","account":{"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","profileId":"65c8f7e2a1b3c4d5e6f7a800","platform":"tiktokads","username":"acme-ads","displayName":"Acme Ads"},"adObject":{"level":"CAMPAIGN","platformId":"1870423600000001","platformAdAccountId":"7505325609036365841","name":"Spring campaign"},"source":"zernio","timestamp":"2026-10-22T09:12:03.120Z"}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"campaign.updated":{"post":{"operationId":"onCampaignUpdated","summary":"Campaign updated event","description":"Fired when a campaign is edited through Zernio (`source: \"zernio\"`) or when the sync detects an edit made outside Zernio (`source: \"platform\"`).\n`changes` lists the edited fields. See `WebhookPayloadCampaignUpdated`.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCampaignUpdated"},"examples":{"sample":{"summary":"Campaign renamed and budget changed","value":{"id":"01J7K3P4N5Q6R7S8T9V0W1X2Z4","event":"campaign.updated","account":{"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","profileId":"65c8f7e2a1b3c4d5e6f7a800","platform":"tiktokads","username":"acme-ads","displayName":"Acme Ads"},"adObject":{"level":"CAMPAIGN","platformId":"1870423600000001","platformAdAccountId":"7505325609036365841","name":"Spring campaign"},"changes":["name","budget"],"source":"zernio","timestamp":"2026-10-22T09:12:03.120Z"}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"ad.review.approved":{"post":{"operationId":"onAdReviewApproved","summary":"Ad review approved event","description":"Fired when an ad Zernio already tracked passes platform review, or a rejection is overturned on appeal. Every ad network.\nSee `WebhookPayloadAdReview` for when it fires and when it does not.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAdReview"},"examples":{"sample":{"summary":"TikTok ad approved","value":{"id":"01J7K3P4N5Q6R7S8T9V0W1X2Z2","event":"ad.review.approved","account":{"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","profileId":"65c8f7e2a1b3c4d5e6f7a800","platform":"tiktokads","username":"acme-ads","displayName":"Acme Ads"},"adObject":{"level":"AD","platformId":"1870423675882786","platformAdAccountId":"7505325609036365841","adId":"65c8f7e2a1b3c4d5e6f7a8c1","name":"Spring promo"},"review":{"status":"approved","raw":"ENABLE","reasons":[]},"timestamp":"2026-10-22T09:12:03.120Z"}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"ad.review.rejected":{"post":{"operationId":"onAdReviewRejected","summary":"Ad review rejected event","description":"Fired when the platform rejects an ad Zernio already tracked. Every ad network.\nSee `WebhookPayloadAdReview` for when it fires and when it does not.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAdReview"},"examples":{"sample":{"summary":"TikTok ad rejected","value":{"id":"01J7K3P4N5Q6R7S8T9V0W1X2Z2","event":"ad.review.rejected","account":{"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","profileId":"65c8f7e2a1b3c4d5e6f7a800","platform":"tiktokads","username":"acme-ads","displayName":"Acme Ads"},"adObject":{"level":"AD","platformId":"1870423675882786","platformAdAccountId":"7505325609036365841","adId":"65c8f7e2a1b3c4d5e6f7a8c1","name":"Spring promo"},"review":{"status":"rejected","raw":"DISABLE","reasons":[{"message":"Ad was rejected by TikTok."}]},"timestamp":"2026-10-22T09:12:03.120Z"}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"ad.delivery_issue":{"post":{"operationId":"onAdDeliveryIssue","summary":"Ad delivery issue event","description":"Fired when an ad Zernio already tracked stops delivering for a platform reason (Meta, TikTok, LinkedIn).\nSee `WebhookPayloadAdDeliveryIssue` for when it fires and when it does not.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAdDeliveryIssue"},"examples":{"sample":{"summary":"Meta ad with a payment issue","value":{"id":"01J7K3P4N5Q6R7S8T9V0W1X2Z2","event":"ad.delivery_issue","account":{"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","profileId":"65c8f7e2a1b3c4d5e6f7a800","platform":"metaads","username":"acme-ads","displayName":"Acme Ads"},"adObject":{"level":"AD","platformId":"120200000000000001","platformAdAccountId":"act_1234567890","adId":"65c8f7e2a1b3c4d5e6f7a8c1","name":"Spring promo"},"issue":{"raw":"WITH_ISSUES","reasons":[{"message":"Your payment method was declined. Update it to resume delivery."}]},"timestamp":"2026-10-22T09:12:03.120Z"}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"campaign.budget.depleted":{"post":{"operationId":"onCampaignBudgetDepleted","summary":"Campaign budget depleted event","description":"Fired when a campaign Zernio already tracked runs out of budget (TikTok).\nSee `WebhookPayloadCampaignBudgetDepleted` for when it fires and when it does not.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCampaignBudgetDepleted"},"examples":{"sample":{"summary":"TikTok campaign out of budget","value":{"id":"01J7K3P4N5Q6R7S8T9V0W1X2Z2","event":"campaign.budget.depleted","account":{"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","profileId":"65c8f7e2a1b3c4d5e6f7a800","platform":"tiktokads","username":"acme-ads","displayName":"Acme Ads"},"adObject":{"level":"CAMPAIGN","platformId":"1800000000000001","platformAdAccountId":"7505325609036365841","name":"Autumn launch"},"budget":{"raw":"AD_STATUS_CAMPAIGN_EXCEED"},"timestamp":"2026-10-22T09:12:03.120Z"}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"ad_account.status_changed":{"post":{"operationId":"onAdAccountStatusChanged","summary":"Ad account status changed event","description":"Fired when an ad account Zernio already tracked changes status (Meta, Google, TikTok, X).\nSee `WebhookPayloadAdAccountStatusChanged` for when it fires and when it does not.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAdAccountStatusChanged"},"examples":{"sample":{"summary":"Meta ad account disabled","value":{"id":"01J7K3P4N5Q6R7S8T9V0W1X2Z2","event":"ad_account.status_changed","account":{"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","profileId":"65c8f7e2a1b3c4d5e6f7a800","platform":"metaads","username":"acme-ads","displayName":"Acme Ads"},"adAccount":{"platformAdAccountId":"act_1234567890","name":"Acme Main"},"status":{"previous":"active","current":"disabled","raw":"2"},"timestamp":"2026-10-22T09:12:03.120Z"}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"ad.video.processed":{"post":{"operationId":"onAdVideoProcessed","summary":"Ad video processed event","description":"Fired once per `POST /v1/ads/videos` call made with `async: true`, when Meta finishes\nprocessing the uploaded video. `video.status` is `ready` (reference it as `video.id`\non the create endpoints) or `error` (Meta could not process it; `video.error` carries\nthe reason).\n\nZernio watches the video for up to about 13 minutes after the upload request. A video\nstill processing after that sends no event, so keep `GET /v1/ads/videos/{videoId}`\nas the source of truth for long videos.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAdVideoProcessed"},"examples":{"ready":{"summary":"Video ready","value":{"id":"01J7K3P4N5Q6R7S8T9V0W1X2Z1","event":"ad.video.processed","account":{"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","profileId":"65c8f7e2a1b3c4d5e6f7a800","platform":"metaads","username":"acme-ads","displayName":"Acme Ads"},"video":{"id":"1096002439847708","platformAdAccountId":"act_2129800524463520","status":"ready","error":null,"thumbnailUrl":"https://scontent.xx.fbcdn.net/v/t15.5256-10/poster.jpg"},"timestamp":"2026-10-05T15:25:27.944Z"}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"ad_rule.triggered":{"post":{"operationId":"onAdRuleTriggered","summary":"Ad rule triggered event","description":"Fired when a scheduled ad rule run finds campaigns or ad sets meeting every condition,\nonce per object per cooldown.\nSee `WebhookPayloadAdRuleTriggered` for when it fires and when it does not.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAdRuleTriggered"},"examples":{"sample":{"summary":"Ad set over its CPA threshold","value":{"id":"01J7K3P4N5Q6R7S8T9V0W1X2Z3","event":"ad_rule.triggered","account":{"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","profileId":"65c8f7e2a1b3c4d5e6f7a800","platform":"metaads","username":"acme-ads","displayName":"Acme Ads"},"rule":{"id":"65c8f7e2a1b3c4d5e6f7a8c1","name":"Pause watch: CPA over 40","level":"adset","platformAdAccountId":"act_1234567890"},"run":{"id":"65c8f7e2a1b3c4d5e6f7a8c2","ranAt":"2026-10-22T09:10:00.000Z","today":"2026-10-22","timezone":"Europe/Madrid","timezoneAssumed":false,"currency":"EUR"},"objects":[{"platformId":"120210000000000002","name":"Prospecting, broad","platformCampaignId":"120210000000000001","conditions":[{"metric":"cpa","window":"last_3d","op":">","value":40,"actual":52.75}],"actions":[{"type":"pause","status":"done","reason":null,"previousDailyBudget":null,"newDailyBudget":null}]}],"timestamp":"2026-10-22T09:10:04.120Z"}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"automation.check.completed":{"post":{"operationId":"onAutomationCheckCompleted","summary":"Automation check completed event","description":"Fired once per scheduled check of an automation, whatever its outcome. See `WebhookPayloadAutomationCheckCompleted`.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAutomationCheckCompleted"},"examples":{"sample":{"summary":"An ad rule check that paused one ad set","value":{"id":"3f1c2a4b-5d6e-4f70-8a9b-0c1d2e3f4a5b","event":"automation.check.completed","automation":{"id":"65c8f7e2a1b3c4d5e6f7a8c1","kind":"ad_rule"},"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","check":{"id":"65c8f7e2a1b3c4d5e6f7a8c2","slot":"2026-10-22T09:17:00.000Z","outcome":"triggered","subjectsEvaluated":12,"actionsCount":1,"error":null},"timestamp":"2026-10-22T09:17:04.000Z"}}}}}},"responses":{"200":{"description":"Webhook received"}}}},"automation.action.applied":{"post":{"operationId":"onAutomationActionApplied","summary":"Automation action applied event","description":"One change an automation made or tried, sent as it settles. See `WebhookPayloadAutomationAction`.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAutomationAction"},"examples":{"sample":{"summary":"A budget raised from 40 to 48","value":{"id":"7a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d","event":"automation.action.applied","automation":{"id":"65c8f7e2a1b3c4d5e6f7a8c1","kind":"ad_rule"},"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","checkId":"65c8f7e2a1b3c4d5e6f7a8c2","action":{"id":"65c8f7e2a1b3c4d5e6f7a8c3","subjectId":"120210000000000002","type":"adjust_budget","status":"applied","reason":null,"previous":{"dailyBudget":40},"target":{"dailyBudget":48},"actedAt":"2026-10-22T09:17:02.000Z"},"timestamp":"2026-10-22T09:17:03.000Z"}}}}}},"responses":{"200":{"description":"Webhook received"}}}},"automation.action.failed":{"post":{"operationId":"onAutomationActionFailed","summary":"Automation action failed event","description":"One change an automation made or tried, sent as it settles. See `WebhookPayloadAutomationAction`.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAutomationAction"},"examples":{"sample":{"summary":"A budget raised from 40 to 48","value":{"id":"7a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d","event":"automation.action.failed","automation":{"id":"65c8f7e2a1b3c4d5e6f7a8c1","kind":"ad_rule"},"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","checkId":"65c8f7e2a1b3c4d5e6f7a8c2","action":{"id":"65c8f7e2a1b3c4d5e6f7a8c3","subjectId":"120210000000000002","type":"adjust_budget","status":"failed","reason":"The platform refused the budget: below the minimum daily budget.","previous":{"dailyBudget":40},"target":{"dailyBudget":48},"actedAt":"2026-10-22T09:17:02.000Z"},"timestamp":"2026-10-22T09:17:03.000Z"}}}}}},"responses":{"200":{"description":"Webhook received"}}}},"automation.action.unknown":{"post":{"operationId":"onAutomationActionUnknown","summary":"Automation action unknown event","description":"One change an automation made or tried, sent as it settles. See `WebhookPayloadAutomationAction`.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAutomationAction"},"examples":{"sample":{"summary":"A budget raised from 40 to 48","value":{"id":"7a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d","event":"automation.action.unknown","automation":{"id":"65c8f7e2a1b3c4d5e6f7a8c1","kind":"ad_rule"},"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","checkId":"65c8f7e2a1b3c4d5e6f7a8c2","action":{"id":"65c8f7e2a1b3c4d5e6f7a8c3","subjectId":"120210000000000002","type":"adjust_budget","status":"unknown","reason":"The platform did not answer in time.","previous":{"dailyBudget":40},"target":{"dailyBudget":48},"actedAt":"2026-10-22T09:17:02.000Z"},"timestamp":"2026-10-22T09:17:03.000Z"}}}}}},"responses":{"200":{"description":"Webhook received"}}}},"automation.alert.opened":{"post":{"operationId":"onAutomationAlertOpened","summary":"Automation alert opened event","description":"An alert episode of an automation with a lifecycle. See `WebhookPayloadAutomationAlert`.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAutomationAlert"},"examples":{"sample":{"summary":"An ad set's alert opened","value":{"id":"7a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c60","event":"automation.alert.opened","automation":{"id":"65c8f7e2a1b3c4d5e6f7a8c1","kind":"ad_rule"},"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","checkId":"65c8f7e2a1b3c4d5e6f7a8c2","alert":{"id":"65c8f7e2a1b3c4d5e6f7a8c4","subjectId":"120210000000000002","severity":"warning","reason":null},"timestamp":"2026-10-22T09:17:03.000Z"}}}}}},"responses":{"200":{"description":"Webhook received"}}}},"automation.alert.escalated":{"post":{"operationId":"onAutomationAlertEscalated","summary":"Automation alert escalated event","description":"An alert episode of an automation with a lifecycle. See `WebhookPayloadAutomationAlert`.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAutomationAlert"},"examples":{"sample":{"summary":"An ad set's alert escalated","value":{"id":"7a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c61","event":"automation.alert.escalated","automation":{"id":"65c8f7e2a1b3c4d5e6f7a8c1","kind":"ad_rule"},"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","checkId":"65c8f7e2a1b3c4d5e6f7a8c2","alert":{"id":"65c8f7e2a1b3c4d5e6f7a8c4","subjectId":"120210000000000002","severity":"critical","reason":null},"timestamp":"2026-10-22T09:17:03.000Z"}}}}}},"responses":{"200":{"description":"Webhook received"}}}},"automation.alert.resolved":{"post":{"operationId":"onAutomationAlertResolved","summary":"Automation alert resolved event","description":"An alert episode of an automation with a lifecycle. See `WebhookPayloadAutomationAlert`.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadAutomationAlert"},"examples":{"sample":{"summary":"An ad set's alert resolved","value":{"id":"7a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c62","event":"automation.alert.resolved","automation":{"id":"65c8f7e2a1b3c4d5e6f7a8c1","kind":"ad_rule"},"accountId":"65c8f7e2a1b3c4d5e6f7a8b9","checkId":"65c8f7e2a1b3c4d5e6f7a8c2","alert":{"id":"65c8f7e2a1b3c4d5e6f7a8c4","subjectId":"120210000000000002","severity":"critical","reason":"condition_cleared"},"timestamp":"2026-10-22T09:17:03.000Z"}}}}}},"responses":{"200":{"description":"Webhook received"}}}},"whatsapp.template.status_updated":{"post":{"operationId":"onWhatsAppTemplateStatusUpdated","summary":"WhatsApp template status updated event","description":"Fired when Meta finishes (re)reviewing a WhatsApp Business template\nattached to a connected WABA. Forwarded from Meta's\n`message_template_status_update` webhook field on the WhatsApp\nBusiness Account. Consumers branch on `template.status` (APPROVED,\nREJECTED, PENDING, PAUSED, DISABLED, IN_APPEAL, PENDING_DELETION).\nMeta does not include the previous status or the template's category\nin this event.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadWhatsAppTemplateStatusUpdated"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"whatsapp.template.category_updated":{"post":{"operationId":"onWhatsAppTemplateCategoryUpdated","summary":"WhatsApp template category updated event","description":"Fired when Meta reclassifies a WhatsApp Business template's category after approval.\n\nIt is forwarded from Meta's `template_category_update` webhook field on the WhatsApp Business Account. Category drives Meta's per-conversation tariff and whether the template is subject to the recipient's marketing opt-out.\n\n- `template.changeType` is `scheduled` (24h advance notice) or `applied`.\n- `template.category` is always the category right now.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadWhatsAppTemplateCategoryUpdated"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"whatsapp.account.quality_updated":{"post":{"operationId":"onWhatsAppAccountQualityUpdated","summary":"WhatsApp quality rating or messaging limit changed","description":"Fired when a connected WhatsApp number's quality rating or messaging limit tier\nchanges. Delivery is at-least-once; dedupe on the event `id`.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadWhatsAppAccountQualityUpdated"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"whatsapp.account.status_updated":{"post":{"operationId":"onWhatsAppAccountStatusUpdated","summary":"WhatsApp Business Account restricted or reinstated","description":"Fired when Meta restricts, disables, deletes or reinstates the WhatsApp Business\nAccount, once per connected number on it.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadWhatsAppAccountStatusUpdated"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"whatsapp.account.alert_received":{"post":{"operationId":"onWhatsAppAccountAlertReceived","summary":"WhatsApp account alert received","description":"Fired for each Meta `account_alerts` notification on a connected WhatsApp\nBusiness Account.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadWhatsAppAccountAlertReceived"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"whatsapp.contact.identity_changed":{"post":{"operationId":"onWhatsAppContactIdentityChanged","summary":"WhatsApp contact identity changed event","description":"Fired when a WhatsApp user changes phone number or Meta regenerates their\nbusiness-scoped user id (BSUID). Carries the previous and current identifiers\nso you can re-key records stored against the old phone number or BSUID.\nDelivery is at-least-once; dedupe on the event `id`.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadWhatsAppContactIdentityChanged"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"whatsapp.account.name_status_updated":{"post":{"operationId":"onWhatsAppAccountNameStatusUpdated","summary":"WhatsApp display-name review outcome event","description":"Fired when Meta finishes reviewing a WhatsApp Business display-name change. Forwarded from Meta's `phone_number_name_update` webhook field on the WhatsApp Business Account.\n\n- It fires only on a review outcome: `name.status` APPROVED, DECLINED, or PENDING_REVIEW.\n- A name applied without review reports `name_status: AVAILABLE_WITHOUT_REVIEW` on the phone node instead, and produces no event here.\n- `decision` REJECTED maps to DECLINED and DEFERRED maps to PENDING_REVIEW, matching the `name_status` vocabulary returned by `GET /v1/whatsapp/number-info`.\n\nDelivery is at-least-once; dedupe on `(account.accountId, name.status, name.requestedName)`.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadWhatsAppAccountNameStatusUpdated"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"whatsapp.automatic_event":{"post":{"operationId":"onWhatsAppAutomaticEvent","summary":"WhatsApp automatic event detected","description":"Fired when Meta's automatic event identification detects a lead or purchase in a Click-to-WhatsApp conversation. The identification is opt-in during Embedded Signup and not available for EU/UK/JP businesses.\n\n- Branch on `eventName` (`LeadSubmitted` | `Purchase`).\n- It carries the `ctwa_clid`.\n\nMeta omits that clid on a minority of referrals on any number (coexistence or not, most often WhatsApp Status placements). When it does, this event can supply it and Zernio writes it back onto the conversation, so POST /v1/whatsapp/conversions becomes usable for the thread.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"event":{"type":"string","enum":["whatsapp.automatic_event"]},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."},"accountId":{"type":"string","description":"SocialAccount id of the WhatsApp number whose conversation was flagged."},"conversationId":{"type":"string","description":"Zernio conversation id, when the thread could be resolved."},"platformMessageId":{"type":"string","description":"The wamid of the message Meta's analysis flagged."},"eventName":{"type":"string","description":"Meta-detected event: `LeadSubmitted` | `Purchase`."},"ctwaClid":{"type":"string","description":"Meta's CTWA click id, the Conversions API match key."},"customData":{"type":"object","description":"Purchase events may carry the detected amount.","properties":{"currency":{"type":"string"},"value":{"type":"number"}}},"detectedAt":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"whatsapp.number.activated":{"post":{"operationId":"onWhatsAppNumberActivated","summary":"WhatsApp number activated event","description":"Fired when a purchased WhatsApp number becomes active and usable. Both\nthe synchronous (Tier 1/2) path and the asynchronous regulated (Tier\n3/4) path land here. Lets integrators react without polling\nGET /v1/phone-numbers.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"event":{"type":"string","enum":["whatsapp.number.activated"]},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."},"number":{"type":"object","properties":{"id":{"type":"string"},"phoneNumber":{"type":"string"},"country":{"type":"string"},"profileId":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"whatsapp.number.declined":{"post":{"operationId":"onWhatsAppNumberDeclined","summary":"WhatsApp number declined event","description":"Fired when a regulated (Tier 3/4) number order is declined or fails\nreview. The number is never billed. `reason` carries the reviewer's\nrejection reason when available.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"event":{"type":"string","enum":["whatsapp.number.declined"]},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."},"number":{"type":"object","properties":{"id":{"type":"string"},"phoneNumber":{"type":"string"},"country":{"type":"string"},"profileId":{"type":"string"}}},"reason":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"whatsapp.number.action_required":{"post":{"operationId":"onWhatsAppNumberActionRequired","summary":"WhatsApp number action required event","description":"Fired when the regulator asks for more information on an already-placed regulated number order.\n\nThe number stays pending (nothing was rejected). The customer can provide the missing information from the dashboard, or via the remediation endpoint.\n\n- `reason` carries the regulator's request verbatim when available.\n- `requirements` lists every requirement on the order with the reviewer's current verdict. The `declined` ones are what to fix, keyed by the same `requirementId` the remediation endpoint uses.\n- Verdicts only change when a reviewer acts, so they describe the review at `reviewedAt`, the time of the reviewer's last comment.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"event":{"type":"string","enum":["whatsapp.number.action_required"]},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."},"reason":{"type":"string"},"requirements":{"type":"array","description":"Every requirement on the order with the reviewer's current verdict. Omitted when the order's requirements could not be read.","items":{"type":"object","properties":{"requirementId":{"type":"string","description":"Same id as fields[].requirementId on the remediation endpoint."},"label":{"type":"string"},"status":{"type":"string","enum":["approved","pending","declined"]}}}},"reviewedAt":{"type":"string","format":"date-time","description":"When the reviewer last commented on the order. Omitted when there is no reviewer comment."},"number":{"type":"object","properties":{"id":{"type":"string"},"phoneNumber":{"type":"string"},"country":{"type":"string"},"profileId":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"whatsapp.number.verification_required":{"post":{"operationId":"onWhatsAppNumberVerificationRequired","summary":"WhatsApp number verification-required event","description":"Fired when a regulated number has an out-of-band identity-verification\nstep (e.g. Onfido). `verificationUrl` is the link to forward to the\nnumber's end user; the order completes once they pass.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"event":{"type":"string","enum":["whatsapp.number.verification_required"]},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."},"number":{"type":"object","properties":{"id":{"type":"string"},"phoneNumber":{"type":"string"},"country":{"type":"string"},"profileId":{"type":"string"}}},"verificationUrl":{"type":"string"}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"whatsapp.number.suspended":{"post":{"operationId":"onWhatsAppNumberSuspended","summary":"WhatsApp number suspended event","description":"Fired when an active number is suspended (e.g. a failed payment). The\nnumber stops working until the issue is resolved, after which a\n`whatsapp.number.reactivated` event is sent. `reason` carries the cause\n(e.g. `payment_failed`, `subscription_ended`).\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"event":{"type":"string","enum":["whatsapp.number.suspended"]},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."},"number":{"type":"object","properties":{"id":{"type":"string"},"phoneNumber":{"type":"string"},"country":{"type":"string"},"profileId":{"type":"string"}}},"reason":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"whatsapp.number.reactivated":{"post":{"operationId":"onWhatsAppNumberReactivated","summary":"WhatsApp number reactivated event","description":"Fired when a suspended number is reactivated (e.g. the payment\nrecovered) and is usable again.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"event":{"type":"string","enum":["whatsapp.number.reactivated"]},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."},"number":{"type":"object","properties":{"id":{"type":"string"},"phoneNumber":{"type":"string"},"country":{"type":"string"},"profileId":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"whatsapp.number.released":{"post":{"operationId":"onWhatsAppNumberReleased","summary":"WhatsApp number released event","description":"Fired when a number is released and is no longer usable (by the user, a\nbilling cleanup, or an admin). Terminal. `reason` carries the cause\n(e.g. `user_requested`, `cleanup_suspended`).\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"event":{"type":"string","enum":["whatsapp.number.released"]},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."},"number":{"type":"object","properties":{"id":{"type":"string"},"phoneNumber":{"type":"string"},"country":{"type":"string"},"profileId":{"type":"string"}}},"reason":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"whatsapp.number.kyc_submitted":{"post":{"operationId":"onWhatsAppNumberKycSubmitted","summary":"WhatsApp number KYC submitted event","description":"Fired when an end customer completes a hosted KYC share link\n(POST /v1/phone-numbers/kyc/share). The number enters review\n(pending_regulatory) under your account; `whatsapp.number.activated` or\n`whatsapp.number.declined` follows once the provider rules on it.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"event":{"type":"string","enum":["whatsapp.number.kyc_submitted","verification.approved","verification.failed"]},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."},"number":{"type":"object","properties":{"id":{"type":"string"},"phoneNumber":{"type":"string"},"country":{"type":"string"},"profileId":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"phone_number.stock_available":{"post":{"operationId":"onPhoneNumberStockAvailable","summary":"Phone-number stock available event","description":"Fired by the stock sweep (every 6h) the first time a country you watch\nvia POST /v1/phone-numbers/stock-watches has deliverable numbers again.\nThe watch is consumed, so the event fires once per watch; the stock\ncounts are a snapshot and numbers are sold first come, first served.\nBuy with POST /v1/phone-numbers/purchase.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadPhoneNumberStockAvailable"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"verification.approved":{"post":{"operationId":"onVerificationApproved","summary":"Verification approved event","description":"Fired when a managed-OTP verification is approved (the user submitted\nthe correct code to POST /v1/verify/verifications/{verificationId}/check).\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"event":{"type":"string","enum":["verification.approved"]},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."},"verification":{"type":"object","properties":{"verificationId":{"type":"string"},"channel":{"type":"string","enum":["sms","whatsapp"]},"to":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"verification.failed":{"post":{"operationId":"onVerificationFailed","summary":"Verification failed event","description":"Fired when a managed-OTP verification is exhausted (the maximum number\nof wrong code attempts was reached).\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"event":{"type":"string","enum":["verification.failed"]},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."},"verification":{"type":"object","properties":{"verificationId":{"type":"string"},"channel":{"type":"string","enum":["sms","whatsapp"]},"to":{"type":"string"}}},"reason":{"type":"string","enum":["max_attempts_reached"]}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"commerce.product.created":{"post":{"operationId":"onCommerceProductCreated","summary":"Commerce product created event","description":"Fired when a product is created on a connected store. The payload carries identifiers only; read the product with\n`GET /v1/commerce/products/{productId}?accountId=...`. Fired once per\nZernio account connected to the store.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCommerceProduct"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"commerce.product.updated":{"post":{"operationId":"onCommerceProductUpdated","summary":"Commerce product updated event","description":"Fired when a product on a connected store changes: its fields, status, variants or prices. The payload carries identifiers only; read the product with\n`GET /v1/commerce/products/{productId}?accountId=...`. Fired once per\nZernio account connected to the store.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCommerceProduct"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"commerce.product.deleted":{"post":{"operationId":"onCommerceProductDeleted","summary":"Commerce product deleted event","description":"Fired when a product is deleted from a connected store. `status` and `platformStatus` are null. The payload carries identifiers only; read the product with\n`GET /v1/commerce/products/{productId}?accountId=...`. Fired once per\nZernio account connected to the store.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCommerceProduct"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"commerce.order.created":{"post":{"operationId":"onCommerceOrderCreated","summary":"Commerce order created event","description":"Fired when an order is placed on a connected store. The payload carries identifiers only; read the order with\n`GET /v1/commerce/orders/{orderId}?accountId=...`. Fired once per\nZernio account connected to the store.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCommerceOrder"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"commerce.order.updated":{"post":{"operationId":"onCommerceOrderUpdated","summary":"Commerce order updated event","description":"Fired when an order on a connected store changes: payment, fulfilment, cancellation, edits, and refunds too. The payload carries identifiers only; read the order with\n`GET /v1/commerce/orders/{orderId}?accountId=...`. Fired once per\nZernio account connected to the store.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCommerceOrder"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"commerce.order.refunded":{"post":{"operationId":"onCommerceOrderRefunded","summary":"Commerce order refunded event","description":"Fired when a refund is issued on an order of a connected store. A commerce.order.updated usually follows for the same change. The payload carries identifiers only; read the order with\n`GET /v1/commerce/orders/{orderId}?accountId=...`. Fired once per\nZernio account connected to the store.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCommerceOrder"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"sms.registration.action_required":{"post":{"operationId":"onSmsRegistrationActionRequired","summary":"SMS registration action required event","description":"Fired when an SMS registration starts waiting on its owner. `reason` says why:\n\n- `changes_requested`: we need answers to some points, before submission or to fix a carrier rejection. `message` is the request; answer with POST /v1/sms/registrations/{id}/respond.\n- `otp_required`: a sole-proprietor brand needs the code texted to its mobile. Submit it with POST /v1/sms/registrations/{id}/verify-otp.\n- `carrier_info_required`: the toll-free carrier asked for more information. The request expires after 7 days.\n\nA carrier rejection alone does not fire it: we handle the fix, see `sms.registration.status_updated`.\n\nIt fires once per new request (not on follow-up messages) and once per OTP or carrier request.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"event":{"type":"string","enum":["sms.registration.action_required"]},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."},"registration":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["standard_10dlc","sole_prop_10dlc","toll_free"]},"displayName":{"type":["string","null"]},"status":{"type":"string","description":"Registration status when the event fired (changes_requested, pending or rejected)."},"profileId":{"type":"string"}}},"reason":{"type":"string","enum":["changes_requested","otp_required","carrier_info_required"]},"message":{"type":"string","description":"What to do, in words: our request or the carrier's note. Absent for otp_required."}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"sms.registration.status_updated":{"post":{"operationId":"onSmsRegistrationStatusUpdated","summary":"SMS registration status updated event","description":"Fired on every status change of an SMS registration:\n\n- `changes_requested`: we need answers, see `sms.registration.action_required`.\n- `requested`: a new submission or resubmit, or your answers are back in our review.\n- `pending`: with the carriers, including after we fixed and resent a rejection.\n- `approved`: live, attach numbers and send.\n- `rejected`: the carriers declined it. `reason` is their words and we handle the fix.\n- `deactivated`.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"event":{"type":"string","enum":["sms.registration.status_updated"]},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."},"registration":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["standard_10dlc","sole_prop_10dlc","toll_free"]},"displayName":{"type":["string","null"]},"status":{"type":"string"},"profileId":{"type":"string"}}},"status":{"type":"string","enum":["changes_requested","requested","pending","approved","rejected","deactivated"]},"reason":{"type":"string","description":"The carriers' decline reason, on rejected."}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"branded_calling.identity.status_updated":{"post":{"operationId":"onBrandedCallingIdentityStatusUpdated","summary":"Caller identity status updated event","description":"Fired on every status change of a Branded Calling caller identity:\n\n- `requested`: a new submission or resubmit, in our review.\n- `changes_requested`: we need answers, see `branded_calling.identity.action_required`.\n- `rejected`: by our review or by the carrier. `reason` says why.\n- `pending_email_verification`: filed with the carrier; the authorizer enters the emailed code.\n- `in_review`: carrier vetting.\n- `verified`: live for a year, attach numbers.\n- `suspended`: an infringement claim is open.\n- `expired`.\n- `permanently_rejected`.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"event":{"type":"string","enum":["branded_calling.identity.status_updated"]},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."},"identity":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"status":{"type":"string"}}},"status":{"type":"string","enum":["requested","changes_requested","rejected","pending_email_verification","in_review","verified","suspended","expired","permanently_rejected"]},"reason":{"type":"string","description":"Our review note, or the carrier's rejection reasons, when there is one."}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"branded_calling.identity.action_required":{"post":{"operationId":"onBrandedCallingIdentityActionRequired","summary":"Caller identity action required event","description":"Fired when a caller identity waits on you. `reason` says what:\n\n- `changes_requested`: answer the review with PATCH.\n- `email_code`: the authorizer got a 6-digit code from the carrier. Confirm it with the verify-email endpoint.\n- `rejected`: the carrier rejected it. Fix and PATCH.\n- `infringement_claim`: a third party disputes the name or logo. Reply to our email with evidence.\n- `expired`: resubmit.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"event":{"type":"string","enum":["branded_calling.identity.action_required"]},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."},"identity":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"status":{"type":"string"}}},"reason":{"type":"string","enum":["changes_requested","email_code","rejected","infringement_claim","expired"]},"message":{"type":"string","description":"What to do, in words."}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"branded_calling.number.status_updated":{"post":{"operationId":"onBrandedCallingNumberStatusUpdated","summary":"Branded number status updated event","description":"Fired when a number attached to a caller identity changes vetting status:\n`in_review`, `verified` (calls from it now show the identity), `unsuccessful`\n(refused; detach and re-add to retry), `suspended`, `expired` or\n`permanently_rejected` (can never be branded again).\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"event":{"type":"string","enum":["branded_calling.number.status_updated"]},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."},"identity":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"}}},"number":{"type":"object","properties":{"phoneNumberId":{"type":"string"},"phoneNumber":{"type":"string"},"status":{"type":"string","enum":["submitted","in_review","verified","unsuccessful","suspended","expired","permanently_rejected"]}}},"reason":{"type":"string","description":"The carrier's rejection detail, when the number was refused."}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"rcs.agent.status_updated":{"post":{"operationId":"onRcsAgentStatusUpdated","summary":"RCS agent status updated event","description":"Fired on every customer-visible status change of an RCS agent:\n\n- `changes_requested`: we need changes before filing. `reason` is our note.\n- `brand_vetting`.\n- `agent_review`.\n- `testing`: add test phones, then send the launch filing. With a `reason`, the launch filing bounced.\n- `launch_review`.\n- `launching`.\n- `live`: the agent can message any RCS-capable phone.\n- `rejected`: `reason` says why.\n- `deactivated`.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"test":{"type":"boolean","description":"Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do."},"id":{"type":"string","description":"Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource."},"profiles":{"$ref":"#/components/schemas/WebhookProfiles"},"event":{"type":"string","enum":["rcs.agent.status_updated"]},"timestamp":{"type":"string","format":"date-time","description":"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt."},"agent":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"profileId":{"type":"string"},"accountId":{"type":["string","null"],"description":"The rcs inbox account, once the agent exists with the carriers."}}},"status":{"type":"string","enum":["changes_requested","brand_vetting","agent_review","testing","launch_review","launching","live","rejected","deactivated"]},"reason":{"type":"string","description":"Our review note on changes_requested, the reason on rejected, or why a launch filing bounced back to testing."}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"api.changelog.published":{"post":{"operationId":"onApiChangelogPublished","summary":"API changelog entry published event","description":"Fired when an entry is published to the API changelog (https://docs.zernio.com/changelog), which happens when a change to this OpenAPI spec goes live.\n\nThe event belongs to no profile or account. Every active subscription that opted in receives it; scoped subscriptions (`profileIds` / `accountIds`) do not.\n\n- `entry.changes` is the deterministic diff of the spec (operations and schemas added, removed and modified).\n- `entry.impact` says whether an existing integration must act (`action_required`), only gained something (`additive`) or nothing changed beyond descriptions (`none`).\n- `entry.message` is the written announcement.\n\nAct on `impact` and `changes`; read `message` for the why. Entries are listed by `GET /v1/changelog`.\n","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadApiChangelogPublished"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"contact.tag_added":{"post":{"operationId":"onContactTagAdded","summary":"Contact tag added event","description":"Fired once per tag a write actually added to a contact, whether the API, a workflow add_tag node or a comment-automation click made it.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadContactTag"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"contact.tag_removed":{"post":{"operationId":"onContactTagRemoved","summary":"Contact tag removed event","description":"Fired once per tag a write actually removed from a contact.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadContactTag"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"contact.field_changed":{"post":{"operationId":"onContactFieldChanged","summary":"Contact field changed event","description":"Fired once per custom field whose value a write changed, with the previous and new value.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadContactFieldChanged"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"sequence.enrolled":{"post":{"operationId":"onSequenceEnrolled","summary":"Sequence enrolled event","description":"Fired when a contact is enrolled in a sequence.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadSequenceEnrollment"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"sequence.exited":{"post":{"operationId":"onSequenceExited","summary":"Sequence exited event","description":"Fired when a contact leaves a sequence, finished or not; exitReason says why.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadSequenceEnrollment"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"workflow.run.started":{"post":{"operationId":"onWorkflowRunStarted","summary":"Workflow run started event","description":"Fired when a workflow run starts for a conversation.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadWorkflowRun"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"workflow.run.completed":{"post":{"operationId":"onWorkflowRunCompleted","summary":"Workflow run completed event","description":"Fired when a workflow run ends; execution.status is completed, or exited for a run ended on purpose before its last node.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadWorkflowRun"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"workflow.run.failed":{"post":{"operationId":"onWorkflowRunFailed","summary":"Workflow run failed event","description":"Fired when a workflow run fails; error says which node failed and why.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadWorkflowRun"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"support.run.completed":{"post":{"operationId":"onSupportRunCompleted","summary":"Support Assistant finished event","description":"Fired when the Support Assistant finishes a question. run.status is completed, or needs_human when the assistant handed the question to a person. The run object matches GET /v1/support/runs/{runId}.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadSupportRun"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"support.run.failed":{"post":{"operationId":"onSupportRunFailed","summary":"Support Assistant failed event","description":"Fired when a Support Assistant question fails or expires. Failed runs are not billed.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadSupportRun"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"campaign_submission.received":{"post":{"operationId":"onCampaignSubmissionReceived","summary":"Campaign submission received event","description":"Fired when a creator submits a post to a campaign and its tracking window opens.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCampaignSubmission"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"campaign_submission.flagged":{"post":{"operationId":"onCampaignSubmissionFlagged","summary":"Campaign submission flagged event","description":"Fired when a submission gains a fraud flag it did not carry before, at submission or on a later sync.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCampaignSubmission"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"campaign_submission.pending_review":{"post":{"operationId":"onCampaignSubmissionPendingReview","summary":"Campaign submission pending review event","description":"Fired when a submission becomes ready for review: a CPM submission reached minViewsToEarn or a pool submission minViewsToQualify; per-post submissions on the first accrual pass after submission.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCampaignSubmission"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"campaign_submission.approved":{"post":{"operationId":"onCampaignSubmissionApproved","summary":"Campaign submission approved event","description":"Fired when an operator approves a submission.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCampaignSubmission"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"campaign_submission.rejected":{"post":{"operationId":"onCampaignSubmissionRejected","summary":"Campaign submission rejected event","description":"Fired when an operator rejects a submission.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCampaignSubmission"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"creator_campaign.closed":{"post":{"operationId":"onCreatorCampaignClosed","summary":"Creator campaign closed event","description":"Fired once when a campaign closes; a pool campaign is split among participants at this moment.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCreatorCampaign"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"campaign_payout.payable":{"post":{"operationId":"onCampaignPayoutPayable","summary":"Campaign payout payable event","description":"Fired when a participant's held earnings mature and become payable.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCampaignPayout"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"campaign_payout.settled":{"post":{"operationId":"onCampaignPayoutSettled","summary":"Campaign payout settled event","description":"Fired when a settlement to a participant is recorded.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCampaignPayout"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"campaign_payout.failed":{"post":{"operationId":"onCampaignPayoutFailed","summary":"Campaign payout failed event","description":"Fired when a treasury payout to a participant is refused, cannot be confirmed, or is reversed. The amount returns to payable, minus anything a rejection claws back.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCampaignPayout"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"campaign_participant.joined":{"post":{"operationId":"onCampaignParticipantJoined","summary":"Campaign participant joined event","description":"Fired once when a creator joins a campaign, from their invite link or the open link.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCampaignParticipant"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"campaign_participant.suspended":{"post":{"operationId":"onCampaignParticipantSuspended","summary":"Campaign participant suspended event","description":"Fired when an operator suspends a participant.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCampaignParticipant"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"campaign_participant.removed":{"post":{"operationId":"onCampaignParticipantRemoved","summary":"Campaign participant removed event","description":"Fired when an operator removes a participant.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCampaignParticipant"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"creator_campaign.budget_exhausted":{"post":{"operationId":"onCreatorCampaignBudgetExhausted","summary":"Creator campaign budget exhausted event","description":"Fired once when a campaign's earnings reach its budget.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadCreatorCampaign"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"webhook.test":{"post":{"operationId":"onWebhookTest","summary":"Webhook test event","description":"Fired when sending a test webhook to verify the endpoint configuration.","tags":["Webhook Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayloadTest"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}}},"security":[{"bearerAuth":[]}],"paths":{"/v1/tools/validate/post-length":{"post":{"x-resource-group":"publishing","operationId":"validatePostLength","tags":["Validate"],"summary":"Validate character count","description":"Check weighted character count per platform and whether the text is within each platform's limit.\n\nReturns counts and limits for all 15 supported platform variants.\n\n### Counting\n\n- X uses weighted counting (URLs = 23 chars via t.co, emojis = 2 chars).\n- All other platforms use plain character length.\n\n### X rows\n\nX returns two rows, and this endpoint cannot tell you which one applies to you: it takes only `text`, so it never resolves an account.\n\n- `twitter` (280) is the free tier limit.\n- `twitterPremium` (25000) applies only when the target X account has a paid X subscription. Publishing enforces 280 instead for any post carrying a poll. This endpoint has no poll input, so the `twitterPremium` row always shows 25000.\n\nA free account trusting the `twitterPremium` row can pass validation here and still fail at publish time, where the account's real limit is enforced.\n\n### Per-account limits\n\nTo validate against the per-account limit, use `POST /v1/tools/validate/post` instead. It accepts an `accountId` per platform entry, resolves X Premium status, and checks the text against the limit publishing enforces, including the poll cap.\n\nA missing, foreign, or invalid `accountId` falls back to the conservative 280.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","description":"The post text to check","example":"Check out https://zernio.com for scheduling posts!"}}}}}},"responses":{"200":{"description":"Character counts per platform","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"platforms":{"type":"object","additionalProperties":{"type":"object","properties":{"count":{"type":"integer","description":"Character count for this platform"},"limit":{"type":"integer","description":"Maximum allowed characters"},"valid":{"type":"boolean","description":"Whether the text is within the limit"}}},"example":{"twitter":{"count":51,"limit":280,"valid":true},"twitterPremium":{"count":51,"limit":25000,"valid":true},"instagram":{"count":51,"limit":2200,"valid":true},"bluesky":{"count":51,"limit":300,"valid":true},"snapchat":{"count":51,"limit":160,"valid":true}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/tools/validate/post":{"post":{"x-resource-group":"publishing","operationId":"validatePost","tags":["Validate"],"summary":"Validate post content","description":"Dry-run the full post validation pipeline without publishing. Catches issues like missing media for Instagram/TikTok/YouTube, hashtag limits, invalid thread formats, Facebook Reel requirements, and character limit violations.\n\nAccepts the same body as POST /v1/posts. Does NOT validate accounts, process media, or track usage. Account lookups are limit-only: a twitter accountId is resolved, scoped to the caller, only to pick the 280 vs 25000 character limit. Missing, foreign, or invalid ids fall back to 280 and never error.\n\nReturns errors for failures and warnings for near-limit content (>90% of character limit).\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platforms"],"properties":{"content":{"type":"string","description":"Post text content","example":"Check out this video!"},"platforms":{"type":"array","description":"Target platforms (same format as POST /v1/posts)","items":{"type":"object","required":["platform"],"properties":{"platform":{"type":"string","enum":["twitter","instagram","tiktok","youtube","facebook","linkedin","bluesky","threads","reddit","pinterest","telegram","snapchat","googlebusiness","discord","slack"]},"accountId":{"type":"string","description":"Account to validate against. For twitter, resolves X Premium status to apply the 25000 character limit instead of 280."},"customContent":{"type":"string"},"platformSpecificData":{"type":"object"},"customMedia":{"type":"array","items":{"$ref":"#/components/schemas/MediaItem"}}}},"example":[{"platform":"youtube"},{"platform":"twitter"}]},"mediaItems":{"type":"array","description":"Root media items shared across platforms","items":{"$ref":"#/components/schemas/MediaItem"}}}}}}},"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Valid post","properties":{"valid":{"type":"boolean"},"message":{"type":"string","example":"No validation issues found."},"warnings":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"warning":{"type":"string"}}}}}},{"type":"object","description":"Invalid post","properties":{"valid":{"type":"boolean"},"errors":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"error":{"type":"string"}}}},"warnings":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"warning":{"type":"string"}}}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/tools/validate/media":{"post":{"x-resource-group":"publishing","operationId":"validateMedia","tags":["Validate"],"summary":"Validate media URL","description":"Check if a media URL is accessible and return metadata (content type, file size) plus per-platform size limit comparisons.\n\nPerforms a HEAD request (with GET fallback) to detect content type and size. Rejects private/localhost URLs for SSRF protection.\n\nPlatform limits are sourced from each platform's actual upload constraints.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Public media URL to validate","example":"https://example.com/image.jpg"}}}}}},"responses":{"200":{"description":"Media validation result","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"url":{"type":"string","format":"uri"},"error":{"type":"string","description":"Error message if valid is false"},"contentType":{"type":"string","example":"image/jpeg"},"size":{"type":["integer","null"],"description":"File size in bytes"},"sizeFormatted":{"type":"string","example":"245 KB"},"type":{"type":"string","enum":["image","video","unknown"]},"platformLimits":{"type":"object","description":"Per-platform size limit comparison (only present when size and type are known)","additionalProperties":{"type":"object","properties":{"limit":{"type":"integer","description":"Platform size limit in bytes"},"limitFormatted":{"type":"string"},"withinLimit":{"type":"boolean"}}},"example":{"instagram":{"limit":8388608,"limitFormatted":"8.0 MB","withinLimit":true},"twitter":{"limit":5242880,"limitFormatted":"5.0 MB","withinLimit":true},"bluesky":{"limit":1000000,"limitFormatted":"977 KB","withinLimit":true}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/tools/validate/subreddit":{"get":{"x-resource-group":"publishing","operationId":"validateSubreddit","tags":["Validate"],"summary":"Check subreddit existence","description":"Temporarily unavailable: Reddit has blocked third-party apps from its API, so this endpoint returns 503 `PLATFORM_DISABLED` until Reddit restores access. Reddit Ads is not affected.\n\nCheck if a subreddit exists and return basic info (title, subscriber count, NSFW status, post types allowed).\n\nWhen accountId is provided, uses authenticated Reddit OAuth API with automatic token refresh (recommended). Falls back to Reddit's public JSON API, which may be unreliable from server IPs. Returns exists: false for private, banned, or nonexistent subreddits.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"name","in":"query","required":true,"description":"Subreddit name (with or without \"r/\" prefix)","schema":{"type":"string","example":"programming"}},{"name":"accountId","in":"query","description":"Reddit account ID for authenticated lookup (recommended for reliable results)","schema":{"type":"string"}}],"responses":{"200":{"description":"Subreddit lookup result","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Subreddit exists","properties":{"exists":{"type":"boolean"},"subreddit":{"type":"object","properties":{"name":{"type":"string","example":"programming"},"title":{"type":"string","example":"programming"},"description":{"type":"string","example":"Computer Programming"},"subscribers":{"type":"integer","example":6844284},"isNSFW":{"type":"boolean"},"type":{"type":"string","enum":["public","private","restricted"],"example":"public"},"allowImages":{"type":"boolean"},"allowVideos":{"type":"boolean"}}}}},{"type":"object","description":"Subreddit not found","properties":{"exists":{"type":"boolean"},"error":{"type":"string"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"description":"Organic Reddit is temporarily unavailable while Reddit blocks third-party API access (`PLATFORM_DISABLED`)."}}}},"/v1/analytics":{"get":{"x-resource-group":"analytics","operationId":"getAnalytics","tags":["Analytics"],"summary":"Get post analytics","description":"Returns analytics for posts. With postId, returns a single post. Without it, returns a paginated list with overview stats.\n\n- Accepts both Zernio Post IDs and External Post IDs (auto-resolved).\n- fromDate defaults to 90 days ago if omitted, max range 366 days.\n- Single post lookups may return 202 (sync pending) or 424 (all platforms failed).\n- For follower stats, use /v1/accounts/follower-stats.\n- Accounts creators connected to your creator campaigns are left out, here and in every other analytics, follower-stats, account health, inbox and external posts read, unless the request names their profileId or accountId.\n\n### LinkedIn personal accounts\n\nAnalytics are only available for posts published through Zernio. LinkedIn's API only returns metrics for posts authored by the authenticated user. Organization/company page analytics work for all posts.\n\n### Facebook Page stories\n\nStories on a connected Page, published through Zernio or natively, are collected while they are live and returned like any other post (platformPostUrl points to the story). Metrics for a story published through Zernio are available on its Zernio post ID.\n\nTheir lifetime metrics refresh about hourly, with a final reading shortly before the story expires at 24 hours. After that the values stay at that last reading.\n\nMapping:\n\n- impressions = story media views (Meta stopped accepting per-story impressions in October 2026, so impressions equals views)\n- reach = unique story media viewers\n- views = story media views\n- likes = story reactions\n- comments = story replies\n- shares = story shares\n- clicks: always 0, because Meta exposes no link-click metric for stories\n","parameters":[{"name":"postId","in":"query","schema":{"type":"string"},"description":"Returns analytics for a single post. Accepts Zernio Post IDs, External Post IDs and the platform's native post ID. Zernio IDs are auto-resolved to External Post analytics."},{"name":"platform","in":"query","schema":{"type":"string"},"description":"Filter by platform (default \"all\")"},{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Filter by profile ID (default \"all\"). With a native postId, selects that profile's copy of the post."},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Filter by account ID. With a native postId, selects that account's copy of the post."},{"name":"source","in":"query","schema":{"type":"string","enum":["all","late","external"],"default":"all"},"description":"Filter by post source: late (posted via Zernio API), external (synced from platform), all (default)"},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Inclusive lower bound (YYYY-MM-DD). Defaults to 90 days ago if omitted. Max range is 366 days."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"Inclusive upper bound (YYYY-MM-DD). Defaults to today if omitted."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size (default 50)"},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number (default 1)"},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["date","engagement","impressions","reach","likes","comments","shares","saves","clicks","views","follows","ig_reels_avg_watch_time","ig_reels_video_view_total_time","reposts","reels_skip_rate","completion_rate","profile_views","website_clicks"],"default":"date"},"description":"Sort by date, engagement, or a specific metric. Platform-specific metrics (follows, reposts, reels_skip_rate, ig_reels_*, completion_rate, profile_views, website_clicks) sort a null value as 0."},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort order"},{"name":"tags","in":"query","schema":{"type":"string","example":"job"},"description":"Comma-separated tags (at most 20). Lists only posts created through Zernio that carry every listed tag, matched exactly and case-sensitively. Up to 200 published posts can match within the date range; more returns 400 asking to narrow fromDate and toDate. Ignored when postId is set."}],"responses":{"200":{"description":"Analytics result","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AnalyticsSinglePostResponse"},{"$ref":"#/components/schemas/AnalyticsListResponse"}]},"examples":{"singlePost":{"summary":"Single post analytics (Zernio post with synced analytics)","value":{"postId":"65f1c0a9e2b5af0012ab34cd","latePostId":null,"status":"published","content":"Check out our new product launch!","scheduledFor":"2024-11-01T10:00:00Z","publishedAt":"2024-11-01T10:00:05Z","analytics":{"impressions":15420,"reach":12350,"likes":342,"comments":28,"shares":45,"saves":0,"clicks":189,"views":0,"engagementRate":2.78,"lastUpdated":"2024-11-02T08:30:00Z"},"platformAnalytics":[{"platform":"twitter","status":"published","platformPostId":"123456789","accountId":"64e1f0a9e2b5af0012ab34cd","accountUsername":"@acmecorp","analytics":{"impressions":15420,"reach":12350,"likes":342,"comments":28,"shares":45,"saves":0,"clicks":189,"views":0,"engagementRate":2.78,"lastUpdated":"2024-11-02T08:30:00Z"},"syncStatus":"synced","platformPostUrl":"https://twitter.com/acmecorp/status/123456789","errorMessage":null}],"platform":"twitter","platformPostUrl":"https://twitter.com/acmecorp/status/123456789","isExternal":false,"syncStatus":"synced","message":null,"thumbnailUrl":"https://storage.example.com/image.jpg","mediaType":"image","mediaItems":[{"type":"image","url":"https://storage.example.com/image.jpg","thumbnail":"https://storage.example.com/image.jpg"}]}},"postList":{"summary":"Paginated analytics list","description":"Note: The list endpoint returns External Post IDs. Posts originally\nscheduled via Zernio will have isExternal: true in this response.\nUse platformPostUrl to correlate with your original Zernio Post IDs.\n","value":{"overview":{"totalPosts":156,"publishedPosts":156,"scheduledPosts":0,"lastSync":"2024-11-02T08:30:00Z","dataStaleness":{"staleAccountCount":0,"syncTriggered":false}},"posts":[{"_id":"65f1c0a9e2b5af0012ab34cd","latePostId":"65f1c0a9e2b5af0012ab34ab","content":"Check out our new product launch!","scheduledFor":"2024-11-01T10:00:00Z","publishedAt":"2024-11-01T10:00:05Z","status":"published","analytics":{"impressions":15420,"reach":12350,"likes":342,"comments":28,"shares":45,"saves":0,"clicks":189,"views":0,"engagementRate":2.78,"lastUpdated":"2024-11-02T08:30:00Z"},"platforms":[{"platform":"instagram","status":"published","platformPostId":"17902345678901234","accountId":"64e1f0a9e2b5af0012ab34cd","accountUsername":"@acmecorp","analytics":{"impressions":15420,"reach":12350,"likes":342,"comments":28,"shares":45,"saves":0,"clicks":189,"views":0,"engagementRate":2.78,"lastUpdated":"2024-11-02T08:30:00Z"},"syncStatus":"synced","platformPostUrl":"https://www.instagram.com/reel/ABC123xyz/","errorMessage":null}],"platform":"instagram","platformPostUrl":"https://www.instagram.com/reel/ABC123xyz/","isExternal":true,"profileId":"64e1f0a9e2b5af0012ab34cd","thumbnailUrl":"https://storage.example.com/thumb.jpg","mediaType":"carousel","mediaItems":[{"type":"image","url":"https://storage.example.com/slide1.jpg","thumbnail":"https://storage.example.com/slide1.jpg"},{"type":"image","url":"https://storage.example.com/slide2.jpg","thumbnail":"https://storage.example.com/slide2.jpg"}]}],"pagination":{"page":1,"limit":50,"total":156,"pages":4},"accounts":[{"_id":"64e1f0...","platform":"twitter","username":"@acmecorp","displayName":"Acme Corp","isActive":true}],"hasAnalyticsAccess":true}}}}}},"202":{"x-summary":"Analytics are still syncing or the post has not finished publishing everywhere: retry later to get the full results.","description":"Analytics are being synced from the platform, or (single post lookup only) the post has not finished publishing on every platform yet.\n\nThe body matches AnalyticsSinglePostResponse with syncStatus \"pending\" and a message.\n\n- While a platform has not published, status is the post's own status (for example scheduled or publishing).\n- A post with one failed platform returns 202 rather than 424 until the others finish.\n- Pending platforms whose account failed its last analytics sync carry that error in platformAnalytics[].errorMessage, and the message says so.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsSinglePostResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid query parameters"},"details":{"type":"object","description":"Detailed validation errors"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Analytics add-on required"},"code":{"type":"string","example":"analytics_addon_required"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"424":{"x-summary":"The post failed to publish on all platforms, so no analytics are available for it.","description":"Post failed to publish on all platforms. Analytics are unavailable. (single post lookup only)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsSinglePostResponse"}}}},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/analytics/delta":{"get":{"x-resource-group":"analytics","operationId":"getAnalyticsDelta","tags":["Analytics"],"summary":"Analytics changed since a cursor","description":"Cursor feed of the analytics snapshots that CHANGED, across every account you can read, in one paginated stream. Built for integrations that would otherwise call `GET /v1/analytics` once per connected account.\n\nEach page carries changes from many accounts at once, so your call count scales with how much actually changed rather than with how many accounts you have.\n\nMeasured against a fleet of roughly 1,600 connected accounts: about 1,599 per-account analytics calls an hour became about 205 delta calls an hour, a 7.8x reduction.\n\n### Bootstrap once, then stay in sync\n\n1. Take the cursor FIRST: call this endpoint with NO `cursor`. It answers with an empty `data` array plus the feed's current position in `nextCursor`.\n2. Load your baseline from `GET /v1/analytics`, the historical endpoint. This one is a rolling 7-day change log and cannot replay history.\n3. Resume from the cursor you took before the baseline.\n\nTaking the cursor afterwards instead drops every change that lands while the baseline is loading: it is in neither the row you already read nor the feed you resume behind it.\n\nThe overlap this order creates is safe. Metrics are absolute values rather than increments, so draining it leaves every post on its newest value.\n\n`nextCursor` is present on every response, empty pages included, so you always have something to advance with.\n\n### Ordering\n\nEntries come back oldest first, in the order the feed received them. That order is NOT `syncedAt`. `syncedAt` is stamped when an account's sync cycle started, and a slow cycle writes its rows after a faster cycle that started later, so `syncedAt` can go backwards between consecutive entries.\n\nDo not sort, filter or resume on `syncedAt`. The cursor is the only stable position, and it is opaque: pass it back verbatim, and do not parse, construct or compare cursors.\n\n### `hasMore: false` does not mean the feed ended\n\nThis stream has no end and `nextCursor` is never null.\n\n- `hasMore: true`: more changes are already waiting, so call again straight away.\n- `hasMore: false`: you are caught up. Keep the cursor and poll again on your normal interval.\n\n### The newest changes settle before they are served\n\nThe feed deliberately holds back its last few seconds of writes, so that a row can never become visible behind a cursor you have already advanced past.\n\nA read issued the instant an `analytics.synced` webhook lands will therefore often return an empty page for that account. Do not read an empty page as \"nothing changed\": poll again with the SAME cursor you last used rather than advancing.\n\n### Repeats inside one instant\n\nA sync cycle occasionally records the same post twice at the same feed position. When that happens the feed delivers one of those rows, not both.\n\nMeasured over a day of production traffic, about 1.3% of rows fall in such a group and 99.4% of those groups are identical rows, so this is far more often deduplication than loss.\n\nMetrics are absolute values rather than increments, so a later entry for the same post supersedes an earlier one.\n\n### Retention is 7 days\n\nChanges older than that leave the feed. A cursor older than 6 days is rejected with a `400` (a day of margin, because expiry is lazy).\n\nRecover the same way you bootstrapped:\n\n1. Take a fresh cursor from a call to this endpoint with no `cursor`.\n2. Re-load from `GET /v1/analytics`.\n3. Resume from that cursor.\n\nA consumer that polls at least daily never reaches this.\n\n### Webhook and access\n\nPairs with the `analytics.synced` webhook, so changes can be read on notification instead of on a timer. That event carries no cursor of its own: keep using the `nextCursor` this endpoint gave you.\n\nRequires the same analytics access as `GET /v1/analytics`, and shares the stricter per-second rate-limit window applied to analytics endpoints.\n","parameters":[{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from a previous response's `nextCursor`. Omit it to start from\nnow: the response is then an empty page carrying the feed's current position.\nRejected with a `400` when malformed, or when older than the retention window.\n","example":"v1.WyIyMDI2LTA5LTAxIDE3OjEyOjA0IiwiNjVmMWMwYTllMmI1YWYwMDEyYWIzNGNkIl0"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size. Out-of-range values are a 400, never a silent clamp."},{"name":"platform","in":"query","schema":{"type":"string"},"description":"Filter to a single platform (for example \"youtube\"). Omit for every platform."},{"name":"profileId","in":"query","schema":{"type":"string","default":"all"},"description":"Filter by profile ID (default \"all\"). Must be a valid profile ID or \"all\"."}],"responses":{"200":{"description":"One page of changed analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsDeltaResponse"},"examples":{"bootstrap":{"summary":"First call, no cursor: an empty page carrying the feed position","value":{"data":[],"nextCursor":"v1.WyIyMDI2LTA5LTAxIDE3OjA4OjUxIiwiIl0","hasMore":false}},"page":{"summary":"A page of changed snapshots","value":{"data":[{"postId":"65f1c0a9e2b5af0012ab34cd","accountId":"64e1f0a9e2b5af0012ab34cd","profileId":"64e1f0a9e2b5af0012ab34aa","platform":"youtube","platformPostId":"dQw4w9WgXcQ","publishedAt":"2026-08-28T10:00:05Z","syncedAt":"2026-09-01T17:11:38Z","isDeleted":false,"metrics":{"impressions":15420,"reach":12350,"likes":342,"comments":28,"shares":45,"saves":12,"sends":0,"clicks":189,"views":9310,"follows":4,"igReelsAvgWatchTime":0,"igReelsVideoViewTotalTime":0,"reposts":0,"reelsSkipRate":0,"completionRate":0,"profileViews":0,"websiteClicks":0,"impressionSources":{},"audienceTypes":{},"audienceCountries":{}}}],"nextCursor":"v1.WyIyMDI2LTA5LTAxIDE3OjEyOjA0IiwiNjVmMWMwYTllMmI1YWYwMDEyYWIzNGNkIl0","hasMore":true}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Analytics add-on required"},"code":{"type":"string","example":"analytics_addon_required"}}}}}},"403":{"x-summary":"The key or caller cannot read this profile, or the profile is beyond the plan's profile limit: use an allowed profile.","description":"The caller cannot read the requested profile, the API key is scoped to other\nprofiles, or the profile sits outside the plan's profile limit (`code`\n`PROFILE_OVER_LIMIT`).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"x-summary":"The delta feed is temporarily unavailable: retry the same request unchanged, waiting the seconds in `Retry-After`.","description":"The delta feed is temporarily unavailable, for example in the minutes between an application release and the analytics store catching up. Nothing is wrong with the request: retry it unchanged, honouring `Retry-After`.\n\nThe feed answers this rather than an empty page, because an empty page is indistinguishable from \"nothing changed\" and would advance you past a window you never received.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/analytics/youtube/channel-insights":{"get":{"x-resource-group":"analytics","operationId":"getYouTubeChannelInsights","tags":["Analytics"],"summary":"Get YouTube channel insights","description":"Returns channel-scoped aggregate metrics from YouTube Analytics API v2. Saves you\nfrom looping /v1/analytics/youtube/daily-views over every video when you only need\nchannel totals.\n\nResponse shape matches /v1/analytics/instagram/account-insights so the same client\nhandling works. Requires yt-analytics.readonly scope (412 with reauthorizeUrl if\nmissing). Data has a 2-3 day delay (endDate is clamped accordingly). Max 89 days,\ndefaults to last 30 days.\n\nNOT exposed: impressions (Studio thumbnail impressions) and impressionsClickThroughRate.\nYouTube Analytics API v2 does not expose these for any principal type, not channel\nowners, not Partner Program channels, not content owners with CMS access. The only way\nto get them is Studio CSV export. This is a Google-side limitation.\n","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The Zernio SocialAccount ID for the YouTube account."},{"name":"metrics","in":"query","schema":{"type":"string"},"description":"Comma-separated list. Defaults to \"views,estimatedMinutesWatched,subscribersGained,subscribersLost\".\n\nLive YouTube Analytics v2 metrics:\n  - views\n  - estimatedMinutesWatched\n  - averageViewDuration          (ratio - weighted mean computed across days)\n  - subscribersGained\n  - subscribersLost\n\nZernio-synthesized from daily follower snapshots (cross-platform parity):\n  - followers_gained\n  - followers_lost\n"},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Start date (YYYY-MM-DD). Defaults to 30 days ago."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"End date (YYYY-MM-DD). Defaults to today. YouTube Analytics has a 2-3 day delay,\nso the fetch is internally clamped to 3 days ago; any requested range extending\nbeyond that returns zero values for the tail days. The response's dateRange.until\nfield reflects your requested value.\n"},{"name":"since","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of fromDate, kept for existing callers"},{"name":"until","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of toDate, kept for existing callers"},{"name":"metricType","in":"query","schema":{"type":"string","enum":["time_series","total_value"],"default":"total_value"},"description":"\"total_value\" (default) returns aggregated totals.\n\"time_series\" returns per-day values in the \"values\" array.\n"}],"responses":{"200":{"description":"Channel insights data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstagramAccountInsightsResponse"}}}},"400":{"description":"Bad request (invalid accountId / metrics / metricType / date range, or account is not a YouTube account)"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans."},"404":{"description":"Account not found"},"412":{"description":"Missing YouTube Analytics scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YouTubeScopeMissingResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamFailure"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/v1/analytics/linkedin/org-aggregate-analytics":{"get":{"x-resource-group":"analytics","operationId":"getLinkedInOrgAggregateAnalytics","tags":["Analytics"],"summary":"Get LinkedIn org analytics","description":"Returns aggregate analytics for a LinkedIn organization page. Parallel to\n/v1/accounts/{id}/linkedin-aggregate-analytics (which handles personal accounts only).\nBacked by LinkedIn's organizationalEntityShareStatistics,\norganizationalEntityFollowerStatistics, and organizationPageStatistics endpoints.\n\nResponse shape matches /v1/analytics/instagram/account-insights. Max 89 days,\ndefaults to last 30 days.\n\nScope requirements: r_organization_social, r_organization_followers, and\nr_organization_admin must all be present on the account. Accounts connected before\nthese scopes were included in the OAuth flow will return 412 with a reauth hint.\n\nEnforced by this endpoint:\n  - Page-view metrics accept only metricType=total_value (LinkedIn omits per-day\n    segmentation even when the API is called with DAY granularity, so a time-series\n    response would be meaningless).\n  - Date range capped at 89 days.\n\nLinkedIn-side platform limits (not re-enforced here, but worth knowing for larger\nranges in a future release):\n  - Follower stats: rolling 12-month window, end must be no later than 2 days ago.\n  - Share stats: rolling 12-month window.\n","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The Zernio SocialAccount ID for the LinkedIn organization account."},{"name":"metrics","in":"query","schema":{"type":"string"},"description":"Comma-separated list. Defaults to\n\"impressions,clicks,engagement_rate,organic_followers_gained,followers_gained,followers_lost\".\n\nShare statistics (support both total_value and time_series):\n  - impressions\n  - unique_impressions\n  - clicks\n  - likes\n  - comments\n  - shares\n  - engagement_rate       (0..1, LinkedIn-computed)\n\nFollower-gain statistics (support total_value and time_series):\n  - organic_followers_gained   (per-day organic gains for time_series; sum of organic gains over the range for total_value)\n  - paid_followers_gained      (per-day paid gains for time_series; sum of paid gains over the range for total_value)\n\nPage-view statistics (total_value ONLY - LinkedIn platform limit):\n  - page_views_total\n  - page_views_overview\n  - page_views_careers\n  - page_views_jobs\n  - page_views_life\n\nZernio-synthesized from daily follower snapshots:\n  - followers_gained\n  - followers_lost\n"},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Start date (YYYY-MM-DD). Defaults to 30 days ago."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"End date (YYYY-MM-DD). Defaults to today."},{"name":"since","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of fromDate, kept for existing callers"},{"name":"until","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of toDate, kept for existing callers"},{"name":"metricType","in":"query","schema":{"type":"string","enum":["time_series","total_value"],"default":"total_value"}}],"responses":{"200":{"description":"Organization analytics data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstagramAccountInsightsResponse"}}}},"400":{"x-summary":"The request is invalid, such as a personal LinkedIn account or a bad metric or date range: fix the parameters and retry.","description":"Bad request. Common cases:\n  - Account is a personal LinkedIn account, not organization (code personal_account_not_supported, use /v1/accounts/{id}/linkedin-aggregate-analytics instead)\n  - Invalid metric name, metricType, or date range\n"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans."},"403":{"x-summary":"The authenticated LinkedIn member lacks the ADMINISTRATOR role on the organization: use a member with that role.","description":"Platform error. The authenticated member lacks the required\nADMINISTRATOR role on the organization. LinkedIn enforces admin-only\naccess for all three org statistics endpoints. The error envelope is\ntype platform_error, and the raw LinkedIn error is echoed in the\nplatformError field.\n"},"404":{"description":"Account not found"},"412":{"description":"Missing LinkedIn organization analytics scopes (r_organization_social + r_organization_followers + r_organization_admin)"}}}},"/v1/analytics/tiktok/account-insights":{"get":{"x-resource-group":"analytics","operationId":"getTikTokAccountInsights","tags":["Analytics"],"summary":"Get TikTok account-level insights","description":"Returns account-level TikTok insights from /v2/user/info/ (live) plus historical time series joined from Zernio's daily snapshotter (AccountStats).\n\n- Response shape matches /v1/analytics/instagram/account-insights.\n- Max 89 days, defaults to last 30 days.\n- Requires the user.info.stats scope on the account (412 if missing).\n\n### Why the scope is narrow\n\nThis ACCOUNT-level endpoint intentionally exposes only the four counter metrics below. It does not return:\n\n- account-level impressions / reach\n- follower inflow / outflow breakdown\n- account-level watch time\n\nFollower age, gender, country and city are on GET /v1/analytics/tiktok/demographics.\n\n### Per-video metrics\n\nPER-VIDEO is a different story on the Business lane. An account connected through the TikTok for Business app reports these per video on GET /v1/analytics?postId=...:\n\n- profile views, website clicks, follows\n- full-watched rate, watch time\n- impression sources, viewer types and viewer countries\n\nThey arrive roughly 24-48h after publishing and only for posts active in the last 7 days.\n\nAccounts on the original TikTok integration get the basic counters there (views, likes, comments, shares) and zeros for the rest. They must reconnect through the Business app.\n","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The Zernio SocialAccount ID for the TikTok account."},{"name":"metrics","in":"query","schema":{"type":"string"},"description":"Comma-separated list. Defaults to\n\"follower_count,likes_count,video_count,followers_gained,followers_lost\".\n\nLive from /v2/user/info/ (requires user.info.stats scope):\n  - follower_count  (cumulative; time series joined from AccountStats)\n  - following_count (cumulative; time series joined from AccountStats.metadata)\n  - likes_count     (cumulative; time series joined from AccountStats.metadata)\n  - video_count     (cumulative; time series joined from AccountStats.metadata)\n\nZernio-synthesized:\n  - followers_gained  (sum of positive daily follower deltas)\n  - followers_lost    (sum of absolute negative daily deltas)\n"},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Start date (YYYY-MM-DD). Defaults to 30 days ago."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"End date (YYYY-MM-DD). Defaults to today."},{"name":"since","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of fromDate, kept for existing callers"},{"name":"until","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of toDate, kept for existing callers"},{"name":"metricType","in":"query","schema":{"type":"string","enum":["time_series","total_value"],"default":"total_value"},"description":"\"total_value\" returns the latest cumulative counter value.\n\"time_series\" returns daily values joined from AccountStats snapshots.\n"}],"responses":{"200":{"description":"Account insights data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstagramAccountInsightsResponse"}}}},"400":{"description":"Bad request (invalid accountId / metrics / metricType / date range, or account is not a TikTok account)"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans."},"404":{"description":"Account not found"},"412":{"description":"Missing user.info.stats scope"}}}},"/v1/analytics/tiktok/demographics":{"get":{"x-resource-group":"analytics","operationId":"getTikTokDemographics","tags":["Analytics"],"summary":"Get TikTok follower demographics","description":"Returns the share of a TikTok account's followers by age, gender, country and city. Without `breakdown` it returns all four.\n\n- Each value is a share of followers from 0 to 1, and each list is sorted largest first. It is not a follower count.\n- Age, gender and country lists add up to 1. The city list can add up to less, because TikTok does not place every follower in a listed city.\n- These are followers of the account, not the viewers of its videos. Viewer countries per video are on GET /v1/analytics?postId=...\n- TikTok updates this data every 24-48 hours.\n\n### Requirements\n\n- The account needs at least 100 followers (400 `tiktok_insufficient_followers` otherwise).\n- The account owner must turn on Analytics in the TikTok app and have published at least one video. Until then an account with enough followers gets empty lists.\n- Requires the user.insights scope, which an account gets by connecting through the TikTok for Business app (412 `tiktok_insights_scope_missing` otherwise). Accounts on the original TikTok integration must reconnect.\n- Requires the Analytics add-on.\n","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The Zernio SocialAccount ID for the TikTok account."},{"name":"breakdown","in":"query","schema":{"type":"string"},"description":"Comma-separated list of demographic dimensions: age, gender, country, city. Defaults to all four."}],"responses":{"200":{"description":"Follower demographics for the account","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"platform":{"type":"string","enum":["tiktok"]},"metric":{"type":"string","enum":["follower_demographics"]},"demographics":{"type":"object","description":"Only the requested breakdowns are present. Entries are sorted by value, largest first.","additionalProperties":{"type":"array","items":{"type":"object","properties":{"dimension":{"type":"string","description":"Age group (18-24, 25-34, 35-44, 45-54, 55+), gender (Female, Male, Other), ISO 3166-1 alpha-2 country code, or city name. `other` collects the countries TikTok does not list individually."},"value":{"type":"number","description":"Share of followers, from 0 to 1"}}}}},"note":{"type":"string"}}},"examples":{"allBreakdowns":{"summary":"Every breakdown","value":{"success":true,"accountId":"64e1a2b3c4d5e6f7a8b9c0d1","platform":"tiktok","metric":"follower_demographics","demographics":{"age":[{"dimension":"25-34","value":0.5},{"dimension":"35-44","value":0.25},{"dimension":"18-24","value":0.25}],"gender":[{"dimension":"Female","value":0.6},{"dimension":"Male","value":0.38},{"dimension":"Other","value":0.02}],"country":[{"dimension":"US","value":0.7},{"dimension":"other","value":0.3}],"city":[{"dimension":"New York","value":0.2}]},"note":"Each value is a share of followers from 0 to 1. TikTok updates this data every 24-48 hours. Empty lists mean TikTok has no data for the account yet: the owner must turn on Analytics in the TikTok app and have published at least one video."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on current plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Analytics add-on required"},"code":{"type":"string","example":"analytics_addon_required"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"412":{"description":"The connection is missing the user.insights scope. Reconnect the account through the TikTok for Business app.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"code":{"type":"string","example":"tiktok_insights_scope_missing"},"scopeStatus":{"type":"object","properties":{"requiresReauthorization":{"type":"boolean"},"hasInsightsScope":{"type":"boolean"}}}}}}}}}}},"/v1/analytics/youtube/daily-views":{"get":{"x-resource-group":"analytics","operationId":"getYouTubeDailyViews","tags":["Analytics"],"summary":"Get YouTube daily views","description":"Returns daily view counts for a YouTube video including views, watch time, and subscriber changes. Requires yt-analytics.readonly scope (re-authorization may be needed).\n\n- YouTube finalizes analytics with a ~3-day delay. By default only finalized days are returned; an explicit endDate can reach into the delay window (see the endDate parameter).\n- Max 90 days, defaults to last 30 days.\n","parameters":[{"name":"videoId","in":"query","required":true,"schema":{"type":"string"},"description":"The YouTube video ID (e.g., \"dQw4w9WgXcQ\")"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The Zernio account ID for the YouTube account"},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Start date (YYYY-MM-DD). Defaults to 30 days ago."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"End date (YYYY-MM-DD). Defaults to 3 days ago, the newest fully finalized day (YouTube finalizes analytics with a ~3-day delay).\n\nAn explicit toDate is honored up to today. Days inside the delay window are provisional and may still be revised by YouTube (see provisionalSince in the response); days YouTube has not processed yet are omitted from dailyViews.\n"},{"name":"startDate","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of fromDate, kept for existing callers"},{"name":"endDate","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of toDate, kept for existing callers"}],"responses":{"200":{"description":"Daily views breakdown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YouTubeDailyViewsResponse"},"examples":{"success":{"summary":"Successful response with daily views","value":{"success":true,"videoId":"dQw4w9WgXcQ","durationSeconds":213,"dateRange":{"startDate":"2025-01-01","endDate":"2025-01-12"},"totalViews":12345,"dailyViews":[{"date":"2025-01-12","views":1234,"estimatedMinutesWatched":567.5,"averageViewDuration":45.2,"averageViewPercentage":21.2,"subscribersGained":10,"subscribersLost":2,"likes":89,"comments":12,"shares":5},{"date":"2025-01-11","views":987,"estimatedMinutesWatched":432.1,"averageViewDuration":43.8,"averageViewPercentage":20.6,"subscribersGained":8,"subscribersLost":1,"likes":67,"comments":8,"shares":3}],"lastSyncedAt":"2025-01-15T12:00:00Z","scopeStatus":{"hasAnalyticsScope":true}}}}}}},"400":{"description":"Bad request (missing or invalid parameters)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"examples":{"missingVideoId":{"value":{"error":"videoId is required"}},"invalidDate":{"value":{"error":"Invalid startDate format. Use YYYY-MM-DD."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Analytics add-on required"},"code":{"type":"string","example":"analytics_addon_required"}}}}}},"403":{"description":"Access denied to this account","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Access denied to this account"}}}}}},"412":{"description":"Missing YouTube Analytics scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YouTubeScopeMissingResponse"},"examples":{"scopeMissing":{"summary":"YouTube Analytics scope not granted","value":{"success":false,"error":"To access daily video analytics, please reconnect your YouTube account to grant the required permissions.","code":"youtube_analytics_scope_missing","scopeStatus":{"hasAnalyticsScope":false,"requiresReauthorization":true,"reauthorizeUrl":"https://accounts.google.com/o/oauth2/auth?client_id=..."}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string"}}}}}}}}},"/v1/analytics/youtube/video-retention":{"get":{"x-resource-group":"analytics","operationId":"getYouTubeVideoRetention","tags":["Analytics"],"summary":"Get YouTube video retention curve","description":"Returns the audience retention curve for a single YouTube video, plus the video's duration for rendering the curve on a time axis. Requires yt-analytics.readonly scope (re-authorization may be needed).\n\n### The curve\n\n- Up to 100 points (elapsedVideoTimeRatio 0.01-1.0), aggregated over the whole date range. YouTube does not support per-day retention breakdowns.\n- audienceWatchRatio: the absolute share of viewers watching at that point in the video. It can exceed 1 (rewinds and looping, common on Shorts).\n- relativeRetentionPerformance: compares against videos of similar length (0 = worst, 0.5 = median, 1 = best).\n- Zernio returns exactly the buckets YouTube reports for the requested range and fills none in. A curve that ends before 1.0, or skips a position, means YouTube returned no row there for that range.\n- The range ends at toDate (default 3 days ago), so recent views are included only with a later toDate.\n\n### Empty curves\n\nYouTube returns an empty curve for videos with very few views or before analytics processing completes (2-3 day delay).\n\n### startedWatching and stoppedWatching\n\nYouTube does not return segment-level data for every video. Zernio then fetches the curve without it: `segmentMetricsAvailable` is `false` and both fields are `0` placeholders in every point. When it is `true`, a `0` is the value YouTube reported.\n","parameters":[{"name":"videoId","in":"query","required":true,"schema":{"type":"string"},"description":"The YouTube video ID (e.g., \"dQw4w9WgXcQ\")"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The Zernio account ID for the YouTube account"},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Start date (YYYY-MM-DD). Defaults to the video's publish date (lifetime curve)."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"End date (YYYY-MM-DD). Defaults to 3 days ago, the newest fully finalized day\n(YouTube finalizes analytics with a ~3-day delay). An explicit toDate is honored\nup to today: days inside the delay window are provisional and may still be revised\nby YouTube (see provisionalSince in the response).\n"},{"name":"startDate","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of fromDate, kept for existing callers"},{"name":"endDate","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of toDate, kept for existing callers"}],"responses":{"200":{"description":"Audience retention curve","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YouTubeVideoRetentionResponse"},"examples":{"success":{"summary":"Successful response with retention curve","value":{"success":true,"accountId":"65f1a2b3c4d5e6f7a8b9c0d1","videoId":"zF7Gp4jnDa0","title":"what's your choice?","publishedAt":"2026-05-20T12:00:00Z","durationSeconds":24,"dateRange":{"startDate":"2026-05-20","endDate":"2026-06-09"},"retentionCurve":[{"elapsedVideoTimeRatio":0.01,"audienceWatchRatio":1.6956,"relativeRetentionPerformance":0.73665,"startedWatching":280331,"stoppedWatching":5348,"totalSegmentImpressions":478466},{"elapsedVideoTimeRatio":0.02,"audienceWatchRatio":1.678,"relativeRetentionPerformance":0.73865,"startedWatching":385,"stoppedWatching":11790,"totalSegmentImpressions":473492}],"segmentMetricsAvailable":true,"scopeStatus":{"hasAnalyticsScope":true}}}}}}},"400":{"description":"Bad request (missing or invalid parameters)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Analytics add-on required"},"code":{"type":"string","example":"analytics_addon_required"}}}}}},"403":{"description":"Access denied to this account","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Access denied to this account"}}}}}},"404":{"description":"Video not found, or it does not belong to this YouTube channel","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Video not found on this YouTube channel"},"type":{"type":"string","example":"not_found"},"code":{"type":"string","example":"video_not_found"},"param":{"type":"string","example":"videoId"}}}}}},"412":{"description":"Missing YouTube Analytics scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YouTubeScopeMissingResponse"},"examples":{"scopeMissing":{"summary":"YouTube Analytics scope not granted","value":{"success":false,"error":"To access video retention analytics, please reconnect your YouTube account to grant the required permissions.","code":"youtube_analytics_scope_missing","scopeStatus":{"hasAnalyticsScope":false,"requiresReauthorization":true,"reauthorizeUrl":"https://accounts.google.com/o/oauth2/auth?client_id=..."}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string"}}}}}}}}},"/v1/analytics/facebook/page-insights":{"get":{"x-resource-group":"analytics","operationId":"getFacebookPageInsights","tags":["Analytics"],"summary":"Get Facebook Page insights","description":"Returns page-level Facebook insights (media views, reach, views, post engagements, reaction counts, video metrics, follower counts). The response shape matches /v1/analytics/instagram/account-insights, so the same client handling works across platforms.\n\nMax 89 days, defaults to last 30 days.\n\n### Metric names\n\nMetric names track the current (post-November 2025) Meta Graph API. These legacy metrics were deprecated by Meta on November 15, 2025 and are NOT accepted by this endpoint:\n\n- page_impressions\n- page_fans\n- page_fan_adds\n- page_fan_removes\n\npage_impressions_unique is deprecated above Graph API v25 and is not accepted; use page_total_media_view_unique. Meta's Page Insights reference (https://developers.facebook.com/docs/graph-api/reference/insights) also deprecates a number of Page Insights metrics for all API versions by June 15, 2026.\n\nUse the replacements below. Because Meta did not provide direct adds/removes replacements, Zernio synthesizes followers_gained / followers_lost from the daily follower snapshotter.\n","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The Zernio SocialAccount ID for the connected Facebook Page."},{"name":"metrics","in":"query","schema":{"type":"string"},"description":"Comma-separated list of metrics. Defaults to \"page_media_view,page_post_engagements,page_follows,followers_gained,followers_lost\".\n\n**Live Meta metrics** (current names, post-Nov-2025):\n\n- page_media_view (replaces deprecated page_impressions)\n- page_total_media_view_unique (reach: unique viewers, replaces deprecated page_impressions_unique). The reach total sums daily unique viewers, not unique people over the range: a viewer seen on several days counts once per day. For a range of exactly 28 days it is Meta's 28-day unique viewers when Meta returns them.\n- page_views_total\n- page_post_engagements (content interactions: reactions, comments, shares and more)\n- page_video_views\n- page_video_view_time\n- page_follows (replaces deprecated page_fans)\n- page_actions_post_reactions_like_total, page_actions_post_reactions_love_total, page_actions_post_reactions_wow_total, page_actions_post_reactions_haha_total, page_actions_post_reactions_sorry_total, page_actions_post_reactions_anger_total (reactions by type; like includes care)\n\n**Zernio-synthesized** from daily follower snapshots (filling the Nov-2025 gap left by the page_fan_adds / page_fan_removes deprecation):\n\n- followers_gained\n- followers_lost\n\n**Monetization** (opt-in, not in the defaults):\n\n- content_monetization_earnings: an object per day, always with unit \"micro_amount\" and an ISO 4217 \"currency\".\n- monetization_approximate_earnings: a bare number per day; unit is always \"unspecified\" and \"currency\" always null.\n\nEach monetization metric costs its own Graph call, so requesting both adds two calls. Values are approximate and Meta restates them later. The two are on different scales and not comparable. Both keep daily \"values\" on every metricType and are never rescaled by Zernio.\n\nEarnings are Page-level daily buckets and \"total\" is their sum. Meta does not document whether a bucket is that day's earnings or a running total, and every Page measured so far earned exactly 0.\n\nReconcile \"total\" against the Page's Meta export before relying on it (daily \"values\" are always returned for this).\n\nPer-post lifetime earnings: GET /v1/analytics/facebook/post-earnings.\n\nA Page not enrolled in monetization, or that earned nothing, returns normal daily buckets of 0 in \"metrics\" (Meta does not distinguish them), so a 0 total does NOT mean the Page is enrolled.\n\n\"unavailableMetrics\" covers the narrower case where Meta returned no bucket at all (\"no_data\") or rejected the request; the metric is then omitted from \"metrics\" rather than reported as 0.\n"},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Start date (YYYY-MM-DD). Defaults to 30 days ago."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"End date (YYYY-MM-DD). Defaults to today."},{"name":"since","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of fromDate, kept for existing callers"},{"name":"until","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of toDate, kept for existing callers"},{"name":"metricType","in":"query","schema":{"type":"string","enum":["time_series","total_value"],"default":"total_value"},"description":"\"total_value\" (default) returns aggregated totals only.\n\"time_series\" returns daily values in the \"values\" array.\n"}],"responses":{"200":{"description":"Page insights data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstagramAccountInsightsResponse"},"examples":{"timeSeries":{"summary":"Time series with computed follower deltas","value":{"success":true,"accountId":"64e1a2b3c4d5e6f7a8b9c0d1","platform":"facebook","dateRange":{"since":"2026-03-01","until":"2026-03-22"},"metricType":"time_series","metrics":{"page_media_view":{"total":125000,"values":[{"date":"2026-03-01","value":5400},{"date":"2026-03-02","value":4820}]},"followers_gained":{"total":142,"values":[{"date":"2026-03-01","value":7},{"date":"2026-03-02","value":5}]},"followers_lost":{"total":23,"values":[{"date":"2026-03-01","value":1},{"date":"2026-03-02","value":0}]}},"dataDelay":"Meta page insights may be delayed up to 24 hours. Metrics reflect the current (post-November 2025) Graph API names. Monetization earnings are approximate and Meta restates them after the fact."}},"monetization":{"summary":"Both monetization metrics, each at its own scale","value":{"success":true,"accountId":"64e1a2b3c4d5e6f7a8b9c0d1","platform":"facebook","dateRange":{"since":"2026-06-01","until":"2026-06-30"},"metricType":"total_value","metrics":{"page_media_view":{"total":125000},"content_monetization_earnings":{"total":1234000000,"unit":"micro_amount","currency":"USD","values":[{"date":"2026-06-01","value":634000000},{"date":"2026-06-02","value":600000000}]},"monetization_approximate_earnings":{"total":1234,"unit":"unspecified","currency":null,"values":[{"date":"2026-06-01","value":700},{"date":"2026-06-02","value":534}]}},"dataDelay":"Meta page insights may be delayed up to 24 hours. Metrics reflect the current (post-November 2025) Graph API names. Monetization earnings are approximate and Meta restates them after the fact."}},"monetizationUnavailable":{"summary":"A monetization metric Meta returned no bucket for","value":{"success":true,"accountId":"64e1a2b3c4d5e6f7a8b9c0d1","platform":"facebook","dateRange":{"since":"2026-06-01","until":"2026-06-30"},"metricType":"total_value","metrics":{"page_media_view":{"total":125000}},"unavailableMetrics":[{"metric":"content_monetization_earnings","reason":"no_data","message":"Meta returned no data for this monetization metric."}],"dataDelay":"Meta page insights may be delayed up to 24 hours. Metrics reflect the current (post-November 2025) Graph API names. Monetization earnings are approximate and Meta restates them after the fact."}}}}}},"400":{"x-summary":"The request is invalid, such as a deprecated metric, a missing Page selection or a wrong account type: fix it and retry.","description":"Bad request. Common cases:\n  - Requested a deprecated metric (page_impressions, page_fans, page_fan_adds, page_fan_removes) - use current names instead\n  - Account has no Page selected (metadata.pageAccessToken missing)\n  - Invalid accountId / metrics / metricType / date range\n  - Account is not a Facebook account\n"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans."},"404":{"description":"Account not found"}}}},"/v1/analytics/facebook/post-earnings":{"get":{"x-resource-group":"analytics","operationId":"getFacebookPostEarnings","tags":["Analytics"],"summary":"Get Facebook post monetization earnings","description":"Returns lifetime monetization earnings for ONE Facebook post, read live from Meta on every request.\n\n### Lifetime totals only\n\nEarnings are CUMULATIVE since the post was published, not earnings within a date range. So this endpoint takes no since/until, and the totals must not be summed across dates or across posts. Page-level daily earnings live on /v1/analytics/facebook/page-insights.\n\n### Zeros and missing metrics\n\n- A post on a Page that is not enrolled in monetization, or that earned nothing, returns \"total\": 0 rather than an error: Meta does not distinguish the two.\n- A metric Meta returned no bucket for at all is reported in \"unavailableMetrics\" and omitted from \"metrics\", never as a 0.\n\nAmounts are the platform's raw numbers in the stated \"unit\" and are never rescaled by Zernio.\n\n### Rejected parameters\n\nThese are rejected with 400:\n\n- \"breakdown\": breakdown dimensions are not exposed.\n- \"since\", \"until\", \"period\", and \"metricType\": scoping this endpoint to a window is not possible.\n\nSilently returning the lifetime total for a window would let a caller sum a year of weekly requests into a figure ~52x the post's real earnings.\n","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The Zernio SocialAccount ID for the connected Facebook Page."},{"name":"postId","in":"query","required":true,"schema":{"type":"string"},"description":"The platform post ID, exactly as returned in platformAnalytics[].platformPostId by\n/v1/analytics: \"{pageId}_{postId}\", or the bare video ID for Reels.\n"},{"name":"metrics","in":"query","schema":{"type":"string"},"description":"Comma-separated list of monetization metrics. Defaults to both:\n  - content_monetization_earnings\n  - monetization_approximate_earnings\n\ncontent_monetization_earnings always carries unit \"micro_amount\" plus an ISO 4217\n\"currency\". monetization_approximate_earnings is always a bare number, so its unit is\n\"unspecified\" and its \"currency\" is null. The two are on different scales and are not\ncomparable to each other. Any other metric name is rejected with 400.\n"}],"responses":{"200":{"description":"Lifetime per-post monetization earnings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacebookPostEarningsResponse"},"examples":{"served":{"summary":"Both metrics served, each at its own scale","value":{"success":true,"accountId":"64e1a2b3c4d5e6f7a8b9c0d1","postId":"123456789_987654321","platform":"facebook","period":"lifetime","metrics":{"content_monetization_earnings":{"total":1234000000,"unit":"micro_amount","currency":"USD"},"monetization_approximate_earnings":{"total":1234,"unit":"unspecified","currency":null}},"dataDelay":"Meta restates monetization earnings after the fact. Per-post earnings are lifetime cumulative: they are the total since publication, not earnings within a date range, and must not be summed across dates."}},"partiallyUnavailable":{"summary":"One metric served, one with no bucket returned by Meta","value":{"success":true,"accountId":"64e1a2b3c4d5e6f7a8b9c0d1","postId":"123456789_987654321","platform":"facebook","period":"lifetime","metrics":{"monetization_approximate_earnings":{"total":0,"unit":"unspecified","currency":null}},"unavailableMetrics":[{"metric":"content_monetization_earnings","reason":"no_data","message":"Meta returned no data for this monetization metric."}],"dataDelay":"Meta restates monetization earnings after the fact. Per-post earnings are lifetime cumulative: they are the total since publication, not earnings within a date range, and must not be summed across dates."}}}}}},"400":{"x-summary":"The request is invalid, such as a non-monetization metric, a date parameter or a missing Page token: fix it and retry.","description":"Bad request. Common cases:\n\n- Invalid accountId format, or a metric name that is not a monetization metric\n- A \"breakdown\" param was supplied (breakdown dimensions are not exposed)\n- A \"since\", \"until\", \"period\", or \"metricType\" param was supplied (this endpoint returns a lifetime total and takes no date range)\n- Account has no Page access token (metadata.pageAccessToken missing)\n- Account is not a Facebook account\n"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans."},"404":{"description":"Account not found"}}}},"/v1/analytics/instagram/account-insights":{"get":{"x-resource-group":"analytics","operationId":"getInstagramAccountInsights","tags":["Analytics"],"summary":"Get Instagram insights","description":"Returns account-level Instagram insights such as reach, views, accounts engaged, and total interactions.\n\nThese metrics reflect the entire account's performance across all content surfaces (feed, stories, explore, profile), and are fundamentally different from post-level metrics.\n\n- Data may be delayed up to 48 hours.\n- Max 90 days (30 for accounts connected through Facebook Login), defaults to last 30 days.\n","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The Zernio SocialAccount ID for the Instagram account"},{"name":"metrics","in":"query","schema":{"type":"string"},"description":"Comma-separated list of metrics. Defaults to \"reach,views,accounts_engaged,total_interactions\".\n\nValid metrics: reach, views, accounts_engaged, total_interactions, comments, likes, saves, shares, replies, reposts, follows_and_unfollows, profile_links_taps, profile_views, website_clicks.\n\nOnly \"reach\" supports metricType=time_series. All other metrics (including follows_and_unfollows, profile_views and website_clicks) are total_value only. This is an Instagram Graph API limitation, not a Zernio one: the IG API returns no time-series data for these metrics.\n\nFor a daily running follower count, use /v1/analytics/instagram/follower-history instead.\n"},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Start date (YYYY-MM-DD). Defaults to 30 days ago."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"End date (YYYY-MM-DD). Defaults to today."},{"name":"since","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of fromDate, kept for existing callers"},{"name":"until","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of toDate, kept for existing callers"},{"name":"metricType","in":"query","schema":{"type":"string","enum":["time_series","total_value"],"default":"total_value"},"description":"\"total_value\" (default) returns aggregated totals and supports breakdowns.\n\"time_series\" returns daily values but only works with the \"reach\" metric.\n"},{"name":"breakdown","in":"query","schema":{"type":"string"},"description":"Breakdown dimension (only valid with metricType=total_value).\nValid values per metric: reach and views take follow_type or media_product_type; follows_and_unfollows takes follow_type; profile_links_taps takes contact_button_type; comments, likes, saves, shares and total_interactions take media_product_type.\n"}],"responses":{"200":{"description":"Account insights data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstagramAccountInsightsResponse"},"examples":{"timeSeries":{"summary":"Time series response with daily values","value":{"success":true,"accountId":"64e1a2b3c4d5e6f7a8b9c0d1","platform":"instagram","dateRange":{"since":"2026-03-01","until":"2026-03-22"},"metricType":"time_series","metrics":{"reach":{"total":12500,"values":[{"date":"2026-03-01","value":420},{"date":"2026-03-02","value":385}]},"views":{"total":45000,"values":[{"date":"2026-03-01","value":1520},{"date":"2026-03-02","value":1380}]}},"dataDelay":"Data may be delayed up to 48 hours"}},"totalValueWithBreakdown":{"summary":"Total value response with media type breakdown","value":{"success":true,"accountId":"64e1a2b3c4d5e6f7a8b9c0d1","platform":"instagram","dateRange":{"since":"2026-03-01","until":"2026-03-22"},"metricType":"total_value","breakdown":"media_product_type","metrics":{"reach":{"total":12500,"breakdowns":[{"dimension":"FEED","value":5000},{"dimension":"REELS","value":7500}]}},"dataDelay":"Data may be delayed up to 48 hours"}}}}}},"400":{"description":"Bad request (invalid parameters)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"examples":{"invalidMetric":{"value":{"error":"Invalid metrics: impressions","validMetrics":["accounts_engaged","comments","follows_and_unfollows","likes","profile_links_taps","profile_views","reach","replies","reposts","saves","shares","total_interactions","views","website_clicks"]}},"breakdownWithTimeSeries":{"value":{"error":"Breakdowns are only supported with metricType=total_value"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Analytics add-on required"},"code":{"type":"string","example":"analytics_addon_required"}}}}}},"403":{"description":"Access denied to this account","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Access denied to this account"}}}}}},"404":{"description":"Account not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Account not found"}}}}}}}}},"/v1/analytics/instagram/follower-history":{"get":{"x-resource-group":"analytics","operationId":"getInstagramFollowerHistory","tags":["Analytics"],"summary":"Get Instagram follower history","description":"Returns a daily running Instagram follower count time series, served from Zernio's\ncross-platform daily snapshotter. Exists because Meta removed follower_count from\nthe /insights endpoint in Graph API v22+ and never exposed a historical daily series\nvia any public API.\n\nResponse envelope matches /v1/analytics/instagram/account-insights so the same client\nhandling works. Max 89 days, defaults to last 30 days.\n","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The Zernio SocialAccount ID for the Instagram account."},{"name":"metrics","in":"query","schema":{"type":"string"},"description":"Comma-separated list. Defaults to \"follower_count,followers_gained,followers_lost\".\n  - follower_count   : per-day raw follower count\n  - followers_gained : sum of positive daily deltas\n  - followers_lost   : sum of absolute negative daily deltas\n"},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Start date (YYYY-MM-DD). Defaults to 30 days ago."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"End date (YYYY-MM-DD). Defaults to today."},{"name":"since","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of fromDate, kept for existing callers"},{"name":"until","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of toDate, kept for existing callers"},{"name":"metricType","in":"query","schema":{"type":"string","enum":["time_series","total_value"],"default":"total_value"},"description":"\"total_value\" returns aggregated totals (latest for follower_count, sum for gained/lost).\n\"time_series\" returns per-day values in the \"values\" array.\n"}],"responses":{"200":{"description":"Follower history data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstagramAccountInsightsResponse"}}}},"400":{"description":"Bad request (invalid accountId / metrics / date range, or account is not an Instagram account)"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans."},"404":{"description":"Account not found"}}}},"/v1/analytics/facebook/demographics":{"get":{"x-resource-group":"analytics","operationId":"getFacebookDemographics","tags":["Analytics"],"summary":"Get Facebook Page demographics","description":"Returns the follower breakdown of a connected Facebook Page by country and/or city, from Meta's latest daily snapshot.\n\n### Keys\n\n- Country keys are ISO 3166-1 alpha-2 codes.\n- City keys are \"City, Region, Country\" strings as Meta returns them.\n\n### Limits\n\nMeta removed age and gender demographics for Pages (page_fans_gender_age) on November 15 2025 with no replacement, so only country and city are available.\n\nMeta reports small counts at a privacy floor, so the long tail can show identical low values.\n","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The Zernio SocialAccount ID for the Facebook account"},{"name":"breakdown","in":"query","schema":{"type":"string"},"description":"Comma-separated list of demographic dimensions: country, city.\nDefaults to both if omitted.\n"}],"responses":{"200":{"description":"Follower demographics for the Page","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"platform":{"type":"string","enum":["facebook"]},"metric":{"type":"string","enum":["follower_demographics"]},"snapshotDate":{"type":["string","null"],"format":"date","description":"Date of Meta's snapshot (YYYY-MM-DD), or null when Meta has no snapshot yet."},"demographics":{"type":"object","description":"Only the requested breakdowns are present. Entries are sorted by value, largest first.","properties":{"country":{"type":"array","items":{"type":"object","properties":{"dimension":{"type":"string"},"value":{"type":"integer","description":"Followers"}}}},"city":{"type":"array","items":{"type":"object","properties":{"dimension":{"type":"string"},"value":{"type":"integer","description":"Followers"}}}}}},"note":{"type":"string"}}},"examples":{"bothBreakdowns":{"summary":"Country and city","value":{"success":true,"accountId":"64e1a2b3c4d5e6f7a8b9c0d1","platform":"facebook","metric":"follower_demographics","snapshotDate":"2026-10-03","demographics":{"country":[{"dimension":"MA","value":145},{"dimension":"IN","value":105}],"city":[{"dimension":"Casablanca, Morocco","value":21},{"dimension":"Johannesburg, South Africa","value":3}]},"note":"Followers by country and city from Meta's latest daily snapshot. Meta removed age and gender for Pages in November 2025."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Analytics add-on required"},"code":{"type":"string","example":"analytics_addon_required"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/analytics/linkedin/demographics":{"get":{"x-resource-group":"analytics","operationId":"getLinkedInDemographics","tags":["Analytics"],"summary":"Get LinkedIn organization follower demographics","description":"Returns the lifetime follower breakdown of a connected LinkedIn organization page by job function, seniority, industry, company size, country and region. Without `breakdown` it returns function, seniority, industry and company size; country and region are returned only when requested.\n\n### Labels\n\n- Function, seniority and industry are labelled with LinkedIn's standardized names (English) and keep the LinkedIn URN in `id`.\n- Company size is labelled as a range such as `2-10` or `10001+`.\n- Country and region are labelled with LinkedIn's geo names (English) and keep `urn:li:geo:*` in `id`. A region is a LinkedIn market area, for example New York City Metropolitan Area.\n\nLinkedIn returns at most the top 100 values per breakdown and leaves out followers whose profile lacks that field, so a breakdown does not add up to the follower count.\n\n### Requirements\n\n- Organization accounts only: a personal LinkedIn account answers 400 `personal_account_not_supported`.\n- Requires the r_organization_social, r_organization_followers and r_organization_admin scopes (412 otherwise).\n- Requires the Analytics add-on.\n","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The Zernio SocialAccount ID of the LinkedIn organization account"},{"name":"breakdown","in":"query","schema":{"type":"string"},"description":"Comma-separated list of demographic dimensions: function, seniority, industry, company_size, country, region.\nDefaults to function, seniority, industry and company_size if omitted. Country and region are returned only when requested.\n"}],"responses":{"200":{"description":"Follower demographics for the organization page","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"platform":{"type":"string","enum":["linkedin"]},"metric":{"type":"string","enum":["follower_demographics"]},"demographics":{"type":"object","description":"Only the requested breakdowns are present. Entries are sorted by value, largest first.","additionalProperties":{"type":"array","items":{"type":"object","properties":{"dimension":{"type":"string","description":"Readable label, or the LinkedIn URN when LinkedIn returns no name for it"},"id":{"type":"string","description":"LinkedIn URN (urn:li:function:8 or urn:li:geo:103644278) or staff count range (SIZE_2_TO_10)"},"value":{"type":"integer","description":"Followers (organic plus paid)"}}}}},"note":{"type":"string"}}},"examples":{"allBreakdowns":{"summary":"Every breakdown","value":{"success":true,"accountId":"64e1a2b3c4d5e6f7a8b9c0d1","platform":"linkedin","metric":"follower_demographics","demographics":{"function":[{"dimension":"Engineering","id":"urn:li:function:8","value":670},{"dimension":"Business Development","id":"urn:li:function:4","value":550}],"seniority":[{"dimension":"Entry","id":"urn:li:seniority:3","value":1010}],"industry":[{"dimension":"Software Development","id":"urn:li:industry:4","value":590}],"company_size":[{"dimension":"2-10","id":"SIZE_2_TO_10","value":690}],"country":[{"dimension":"United States","id":"urn:li:geo:103644278","value":820}],"region":[{"dimension":"New York City Metropolitan Area","id":"urn:li:geo:90000070","value":310}]},"note":"Lifetime breakdown of the organization page followers. LinkedIn returns at most the top 100 values per breakdown and leaves out followers whose profile lacks that field, so a breakdown does not add up to the follower count."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Analytics add-on required"},"code":{"type":"string","example":"analytics_addon_required"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"412":{"x-summary":"The LinkedIn connection lacks the organization analytics scopes: reconnect the account to grant them.","description":"The LinkedIn connection is missing the organization analytics scopes. Reconnect the account to grant them.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","example":"linkedin_org_analytics_scope_missing"}}}}}}}}},"/v1/analytics/instagram/demographics":{"get":{"x-resource-group":"analytics","operationId":"getInstagramDemographics","tags":["Analytics"],"summary":"Get Instagram demographics","description":"Returns audience demographic insights for an Instagram account, broken down by age, city, country, and/or gender.\nRequires at least 100 followers. Returns top 45 entries per dimension.\nData may be delayed up to 48 hours.\n","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The Zernio SocialAccount ID for the Instagram account"},{"name":"metric","in":"query","schema":{"type":"string","enum":["follower_demographics","engaged_audience_demographics"],"default":"follower_demographics"},"description":"\"follower_demographics\" for follower audience data, or \"engaged_audience_demographics\" for engaged viewers.\n"},{"name":"breakdown","in":"query","schema":{"type":"string"},"description":"Comma-separated list of demographic dimensions: age, city, country, gender.\nDefaults to all four if omitted.\n"},{"name":"timeframe","in":"query","schema":{"type":"string","enum":["this_week","this_month"],"default":"this_month"},"description":"Time period for demographic data. Defaults to \"this_month\".\n"}],"responses":{"200":{"description":"Demographic insights data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstagramDemographicsResponse"},"examples":{"allBreakdowns":{"summary":"All four demographic breakdowns","value":{"success":true,"accountId":"64e1a2b3c4d5e6f7a8b9c0d1","platform":"instagram","metric":"follower_demographics","timeframe":"last_30_days","demographics":{"age":[{"dimension":"25-34","value":4500},{"dimension":"18-24","value":3200}],"gender":[{"dimension":"M","value":3000},{"dimension":"F","value":4800}],"city":[{"dimension":"New York, New York","value":800},{"dimension":"Los Angeles, California","value":650}],"country":[{"dimension":"US","value":5000},{"dimension":"GB","value":1200}]},"note":"Demographics show top 45 entries per dimension. Requires 100+ followers."}}}}}},"400":{"description":"Bad request (invalid parameters)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"examples":{"invalidBreakdown":{"value":{"error":"Invalid breakdowns: location","validBreakdowns":["age","city","country","gender"]}},"insufficientFollowers":{"value":{"success":false,"error":"Demographic insights require at least 100 followers.","code":"instagram_insufficient_followers"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Analytics add-on required"},"code":{"type":"string","example":"analytics_addon_required"}}}}}},"403":{"description":"Access denied to this account","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Access denied to this account"}}}}}},"404":{"description":"Account not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Account not found"}}}}}}}}},"/v1/analytics/instagram/online-followers":{"get":{"x-resource-group":"analytics","operationId":"getInstagramOnlineFollowers","tags":["Analytics"],"summary":"Get Instagram online followers","description":"Returns how many of an Instagram account's followers were online in each hour, for every day of the last 30 days that Meta has data for.\n\n- Hour keys are \"0\" to \"23\" as Meta returns them. Meta does not document the timezone of the hour keys.\n- endTime is the end_time Meta returns for that day.\n- Data is delayed up to 48 hours, so the most recent days are left out until Meta fills them.\n- Requires at least 100 followers; for smaller accounts days is empty.\n","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The Zernio SocialAccount ID for the Instagram account"}],"responses":{"200":{"description":"Followers online per hour, one entry per day with data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"platform":{"type":"string","enum":["instagram"]},"metric":{"type":"string","enum":["online_followers"]},"days":{"type":"array","description":"Oldest first, as Meta returns them. Days Meta still reports as empty are left out.","items":{"type":"object","properties":{"endTime":{"type":"string","description":"The end_time Meta returns for this day."},"hours":{"type":"object","description":"Followers online per hour, keyed \"0\" to \"23\".","additionalProperties":{"type":"integer"}}}}},"note":{"type":"string"}}},"examples":{"twoDays":{"summary":"Two days with hourly data","value":{"success":true,"accountId":"64e1a2b3c4d5e6f7a8b9c0d1","platform":"instagram","metric":"online_followers","days":[{"endTime":"2026-10-01T07:00:00+0000","hours":{"0":120,"1":98,"2":75,"3":61,"4":58,"5":70,"6":104,"7":150,"8":188,"9":210,"10":225,"11":231,"12":240,"13":236,"14":229,"15":233,"16":245,"17":262,"18":281,"19":290,"20":284,"21":251,"22":203,"23":158}},{"endTime":"2026-10-02T07:00:00+0000","hours":{"0":117,"1":95,"2":77,"3":63,"4":55,"5":72,"6":101,"7":148,"8":190,"9":207,"10":222,"11":235,"12":238,"13":230,"14":226,"15":239,"16":248,"17":266,"18":279,"19":293,"20":280,"21":249,"22":206,"23":160}}],"note":"Followers online per hour over the last 30 days. Meta delays data up to 48 hours and returns nothing for accounts under 100 followers."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Analytics add-on required"},"code":{"type":"string","example":"analytics_addon_required"}}}}}},"403":{"x-summary":"The API key cannot reach this account because of its profile scope or a disabled analytics group: use a key with access.","description":"The API key cannot reach this account: the account's profile is outside the key's profile scope, or the key's analytics resource group is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"This API key does not have access to this profile"}}}},"404":{"$ref":"#/components/responses/NotFound"},"502":{"$ref":"#/components/responses/UpstreamFailure"}}}},"/v1/analytics/youtube/demographics":{"get":{"x-resource-group":"analytics","operationId":"getYouTubeDemographics","tags":["Analytics"],"summary":"Get YouTube demographics","description":"Returns audience demographic insights for a YouTube channel, broken down by age, gender, and/or country. Pass videoId to get the audience profile of a single video instead of the whole channel.\n\n- Age and gender values are viewer percentages (0-100).\n- Country values are view counts.\n\nData is based on signed-in viewers only, with a 2-3 day delay. YouTube suppresses demographics for videos with too few signed-in views, so low-traffic videos can return empty breakdowns.\n","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The Zernio SocialAccount ID for the YouTube account"},{"name":"videoId","in":"query","schema":{"type":"string"},"description":"YouTube video ID. When provided, demographics are scoped to this single video\n(must belong to the connected channel; otherwise 404 video_not_found).\n"},{"name":"breakdown","in":"query","schema":{"type":"string"},"description":"Comma-separated list of demographic dimensions: age, gender, country.\nDefaults to all three if omitted.\n"},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Start date in YYYY-MM-DD format. Defaults to 90 days ago, or to the video's\npublish date (lifetime) when videoId is provided.\n"},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"End date (YYYY-MM-DD). Defaults to 3 days ago, the newest fully finalized day\n(YouTube finalizes analytics with a ~3-day delay). An explicit toDate is honored\nup to today: days inside the delay window are provisional and may still be revised\nby YouTube (see provisionalSince in the response).\n"},{"name":"startDate","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of fromDate, kept for existing callers"},{"name":"endDate","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of toDate, kept for existing callers"}],"responses":{"200":{"description":"Demographic insights data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YouTubeDemographicsResponse"},"examples":{"allBreakdowns":{"summary":"All three demographic breakdowns","value":{"success":true,"accountId":"64e1a2b3c4d5e6f7a8b9c0d1","platform":"youtube","demographics":{"age":[{"dimension":"25-34","value":28.5},{"dimension":"18-24","value":22.1}],"gender":[{"dimension":"male","value":62.3},{"dimension":"female","value":35.8}],"country":[{"dimension":"US","value":12000},{"dimension":"GB","value":3500}]},"dateRange":{"startDate":"2026-01-01","endDate":"2026-03-31"},"note":"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."}},"singleVideo":{"summary":"Demographics scoped to one video (videoId provided)","value":{"success":true,"accountId":"64e1a2b3c4d5e6f7a8b9c0d1","platform":"youtube","videoId":"dQw4w9WgXcQ","title":"Product launch teaser","publishedAt":"2026-06-01T09:00:00.000Z","demographics":{"age":[{"dimension":"25-34","value":41.2}],"gender":[{"dimension":"male","value":75},{"dimension":"female","value":25}],"country":[{"dimension":"MX","value":394},{"dimension":"AR","value":181}]},"dateRange":{"startDate":"2026-06-01","endDate":"2026-07-13"},"note":"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."}}}}}},"400":{"description":"Bad request (invalid parameters or not a YouTube account)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Analytics add-on required"},"code":{"type":"string","example":"analytics_addon_required"}}}}}},"403":{"description":"Access denied to this account, or the connected YouTube account or channel is suspended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Access denied to this account"}}}}}},"404":{"description":"Account not found, or the video does not exist / does not belong to this YouTube channel","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Account not found"}}}}}},"412":{"description":"YouTube Analytics scope not granted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string"},"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"}}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamFailure"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/v1/analytics/daily-metrics":{"get":{"x-resource-group":"analytics","operationId":"getDailyMetrics","tags":["Analytics"],"summary":"Get daily aggregated metrics","description":"Returns daily aggregated analytics metrics and a per-platform breakdown.\nEach day includes post count, platform distribution, and summed metrics (impressions, reach, likes, comments, shares, saves, clicks, views).\nDefaults to the last 180 days.\n\n`totals` sums the whole range for the applied filters (pass `accountId` for one account). With attribution \"publish\" they are the lifetime metrics of posts published in the range, with \"received\" the engagement that arrived in the range.\n","parameters":[{"name":"platform","in":"query","schema":{"type":"string"},"description":"Filter by platform (e.g. \"instagram\", \"tiktok\"). Omit for all platforms."},{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Filter by profile ID. Omit for all profiles."},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Filter by account ID"},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date-time"},"description":"Inclusive start date (ISO 8601). Defaults to 180 days ago."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date-time"},"description":"Inclusive end date (ISO 8601). Defaults to now."},{"name":"source","in":"query","schema":{"type":"string","enum":["all","late","external"],"default":"all"},"description":"Filter by post origin. \"late\" for posts published via Zernio, \"external\" for posts imported from platforms."},{"name":"attribution","in":"query","schema":{"type":"string","enum":["publish","received"],"default":"publish"},"description":"How each post's engagement is attributed to a day.\n\n- \"publish\" (default): sums each post's lifetime total on its publish date.\n- \"received\": buckets the per-day increase in engagement by the day it actually arrived (engagement-over-time), so engagement on older posts appears on the day it was gained rather than the post's publish date.\n"}],"responses":{"200":{"description":"Daily metrics and platform breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"dailyData":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2025-12-01"},"postCount":{"type":"integer","example":3},"platforms":{"type":"object","additionalProperties":{"type":"integer"},"example":{"instagram":2,"twitter":1}},"metrics":{"type":"object","properties":{"impressions":{"type":"integer"},"reach":{"type":"integer"},"likes":{"type":"integer"},"comments":{"type":"integer"},"shares":{"type":"integer"},"saves":{"type":"integer"},"clicks":{"type":"integer"},"views":{"type":"integer"}}}}}},"platformBreakdown":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","example":"instagram"},"postCount":{"type":"integer","example":142},"impressions":{"type":"integer"},"reach":{"type":"integer"},"likes":{"type":"integer"},"comments":{"type":"integer"},"shares":{"type":"integer"},"saves":{"type":"integer"},"clicks":{"type":"integer"},"views":{"type":"integer"}}}},"totals":{"type":"object","description":"Sums of the whole range for the applied filters.","properties":{"postCount":{"type":"integer"},"impressions":{"type":"integer"},"reach":{"type":"integer","description":"Sum of per-post reach, not unique accounts."},"likes":{"type":"integer"},"comments":{"type":"integer"},"shares":{"type":"integer"},"saves":{"type":"integer"},"clicks":{"type":"integer"},"views":{"type":"integer"},"engagement":{"type":"integer","description":"Likes, comments, shares and saves (interactions)."}}}}},"examples":{"success":{"value":{"dailyData":[{"date":"2025-12-01","postCount":3,"platforms":{"instagram":2,"twitter":1},"metrics":{"impressions":4520,"reach":3200,"likes":312,"comments":45,"shares":28,"saves":67,"clicks":89,"views":1560}}],"platformBreakdown":[{"platform":"instagram","postCount":142,"impressions":89400,"reach":62100,"likes":8930,"comments":1204,"shares":567,"saves":2103,"clicks":3402,"views":45200}],"totals":{"postCount":142,"impressions":89400,"reach":62100,"likes":8930,"comments":1204,"shares":567,"saves":2103,"clicks":3402,"views":45200,"engagement":12804}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Analytics add-on required"},"code":{"type":"string","example":"analytics_addon_required"}}}}}},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"}}}},"/v1/analytics/dashboard":{"get":{"x-resource-group":"analytics","operationId":"getAnalyticsDashboard","tags":["Analytics"],"summary":"Get an analytics dashboard","description":"Everything an analytics dashboard needs in one call: window totals, follower growth, a per-day series, top posts, recent posts and, optionally, the same figures for the previous period.\n\nAll dates are UTC days.\n\n### Daily and total metrics\n\nDaily and total metrics use received attribution: each day holds the engagement that arrived that day, on any post. So `totals` is always the sum of `daily`.\n\n### Post lists\n\n`topPosts` and `recentPosts` list posts published in the window with their lifetime metrics. A post cross-posted to several platforms appears once per platform.\n","parameters":[{"name":"profileId","in":"query","schema":{"type":"string","default":"all"},"description":"Profile ID, or \"all\" for every profile you can access."},{"name":"platform","in":"query","schema":{"type":"string","default":"all"},"description":"Platform to cover (e.g. \"instagram\"), or \"all\"."},{"name":"fromDate","in":"query","required":true,"schema":{"type":"string","format":"date","example":"2026-09-01"},"description":"First day of the window (YYYY-MM-DD, inclusive)."},{"name":"toDate","in":"query","required":true,"schema":{"type":"string","format":"date","example":"2026-09-30"},"description":"Last day of the window (YYYY-MM-DD, inclusive). May equal fromDate. The window covers at most 366 days."},{"name":"compare","in":"query","schema":{"type":"string","enum":["previous_period"]},"description":"Set to \"previous_period\" to also return previousTotals and previousFollowers for the window of the same length that ends the day before fromDate."},{"name":"topPosts","in":"query","schema":{"type":"integer","minimum":0,"maximum":25,"default":5},"description":"How many top posts to return, ranked by engagement (likes, comments, shares and saves, the same sum as daily engagement)."},{"name":"recentPosts","in":"query","schema":{"type":"integer","minimum":0,"maximum":25,"default":10},"description":"How many of the most recently published posts to return."}],"responses":{"200":{"description":"Dashboard for the window","content":{"application/json":{"schema":{"type":"object","required":["dateRange","totals","followers","daily","topPosts","recentPosts","dataAsOf"],"properties":{"dateRange":{"type":"object","properties":{"fromDate":{"type":"string","format":"date"},"toDate":{"type":"string","format":"date"}}},"totals":{"$ref":"#/components/schemas/AnalyticsDashboardTotals"},"previousTotals":{"$ref":"#/components/schemas/AnalyticsDashboardTotals"},"followers":{"$ref":"#/components/schemas/AnalyticsDashboardFollowers"},"previousFollowers":{"$ref":"#/components/schemas/AnalyticsDashboardFollowers"},"daily":{"type":"array","description":"One entry per day of the window, days without data included as zeros.","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"impressions":{"type":"integer"},"reach":{"type":"integer"},"engagement":{"type":"integer","description":"Likes, comments, shares and saves received that day."},"views":{"type":"integer"},"followersGained":{"type":"integer","description":"Net follower change against the previous snapshot. Can be negative."}}}},"topPosts":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsDashboardPost"}},"recentPosts":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsDashboardPost"}},"dataAsOf":{"type":["string","null"],"format":"date-time","description":"When the most recently synced account in scope was last synced. Null if none has synced yet."}}},"examples":{"success":{"value":{"dateRange":{"fromDate":"2026-09-01","toDate":"2026-09-02"},"totals":{"impressions":5400,"reach":4100,"likes":320,"comments":41,"shares":18,"saves":25,"clicks":60,"views":2200,"engagementRate":7.48},"followers":{"current":12840,"gained":96,"byAccount":[{"accountId":"64e1f0a9c2b4d5e6f7a8b9c0","platform":"instagram","current":12840,"gained":96}]},"daily":[{"date":"2026-09-01","impressions":2900,"reach":2200,"engagement":210,"views":1200,"followersGained":0},{"date":"2026-09-02","impressions":2500,"reach":1900,"engagement":194,"views":1000,"followersGained":96}],"topPosts":[{"postId":"65f1c0a9e2b4d5f6a7b8c9d0","platform":"instagram","publishedAt":"2026-09-01T15:00:00.000Z","metrics":{"impressions":3100,"reach":2600,"likes":210,"comments":22,"shares":9,"saves":14,"clicks":30,"views":1500,"engagementRate":8.23}}],"recentPosts":[],"dataAsOf":"2026-09-02T23:10:00.000Z"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans."},"403":{"description":"The profile is not accessible, or is beyond your plan's profile limit (PROFILE_OVER_LIMIT)."},"404":{"description":"Profile not found or not accessible with this API key."},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"}}}},"/v1/analytics/best-time":{"get":{"x-resource-group":"analytics","operationId":"getBestTimeToPost","tags":["Analytics"],"summary":"Get best times to post","description":"Returns the best times to post based on historical engagement data.\nGroups all published posts by day of week and hour (UTC), calculating average engagement per slot.\nUse this to auto-schedule posts at optimal times.\n","parameters":[{"name":"platform","in":"query","schema":{"type":"string"},"description":"Filter by platform (e.g. \"instagram\", \"tiktok\"). Omit for all platforms."},{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Filter by profile ID. Omit for all profiles."},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Filter by account ID. Omit for all accounts."},{"name":"source","in":"query","schema":{"type":"string","enum":["all","late","external"],"default":"all"},"description":"Filter by post origin. \"late\" for posts published via Zernio, \"external\" for posts imported from platforms."}],"responses":{"200":{"description":"Best time slots","content":{"application/json":{"schema":{"type":"object","properties":{"slots":{"type":"array","items":{"type":"object","properties":{"day_of_week":{"type":"integer","description":"0=Monday, 6=Sunday","minimum":0,"maximum":6},"hour":{"type":"integer","description":"Hour in UTC (0-23)","minimum":0,"maximum":23},"avg_engagement":{"type":"number","description":"Average engagement (likes + comments + shares + saves)"},"post_count":{"type":"integer","description":"Number of posts in this slot"}}}}}},"examples":{"success":{"value":{"slots":[{"day_of_week":2,"hour":18,"avg_engagement":510.3,"post_count":15},{"day_of_week":0,"hour":9,"avg_engagement":342.5,"post_count":12},{"day_of_week":4,"hour":12,"avg_engagement":289.1,"post_count":8}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Analytics add-on required"},"requiresAddon":{"type":"boolean","example":true}}}}}},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"}}}},"/v1/analytics/content-decay":{"get":{"x-resource-group":"analytics","operationId":"getContentDecay","tags":["Analytics"],"summary":"Get content performance decay","description":"Returns how engagement accumulates over time after a post is published.\nEach bucket shows what percentage of the post's total engagement had been reached by that time window.\nUseful for understanding content lifespan (e.g. \"posts reach 78% of total engagement within 24 hours\").\n","parameters":[{"name":"platform","in":"query","schema":{"type":"string"},"description":"Filter by platform (e.g. \"instagram\", \"tiktok\"). Omit for all platforms."},{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Filter by profile ID. Omit for all profiles."},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Filter by account ID. Omit for all accounts."},{"name":"source","in":"query","schema":{"type":"string","enum":["all","late","external"],"default":"all"},"description":"Filter by post origin. \"late\" for posts published via Zernio, \"external\" for posts imported from platforms."}],"responses":{"200":{"description":"Content decay buckets","content":{"application/json":{"schema":{"type":"object","properties":{"buckets":{"type":"array","items":{"type":"object","properties":{"bucket_order":{"type":"integer","description":"Sort order (0 = earliest, 6 = latest)"},"bucket_label":{"type":"string","description":"Human-readable label"},"avg_pct_of_final":{"type":"number","description":"Average % of final engagement reached (0-100)"},"post_count":{"type":"integer","description":"Number of posts with data in this bucket"}}}}}},"examples":{"success":{"value":{"buckets":[{"bucket_order":0,"bucket_label":"0-6h","avg_pct_of_final":45.2,"post_count":89},{"bucket_order":1,"bucket_label":"6-12h","avg_pct_of_final":18.7,"post_count":89},{"bucket_order":2,"bucket_label":"12-24h","avg_pct_of_final":14.1,"post_count":85},{"bucket_order":3,"bucket_label":"1-2d","avg_pct_of_final":9.3,"post_count":82},{"bucket_order":4,"bucket_label":"2-7d","avg_pct_of_final":8.1,"post_count":78},{"bucket_order":5,"bucket_label":"7-30d","avg_pct_of_final":3.8,"post_count":64},{"bucket_order":6,"bucket_label":"30d+","avg_pct_of_final":0.8,"post_count":41}]}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Analytics add-on required"},"requiresAddon":{"type":"boolean","example":true}}}}}},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"}}}},"/v1/analytics/posting-frequency":{"get":{"x-resource-group":"analytics","operationId":"getPostingFrequency","tags":["Analytics"],"summary":"Get frequency vs engagement","description":"Returns the correlation between posting frequency (posts per week) and engagement rate, broken down by platform.\nHelps find the optimal posting cadence for each platform. Each row represents a specific (platform, posts_per_week) combination\nwith the average engagement rate observed across all weeks matching that frequency.\n","parameters":[{"name":"platform","in":"query","schema":{"type":"string"},"description":"Filter by platform (e.g. \"instagram\", \"tiktok\"). Omit for all platforms."},{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Filter by profile ID. Omit for all profiles."},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Filter by account ID. Omit for all accounts."},{"name":"source","in":"query","schema":{"type":"string","enum":["all","late","external"],"default":"all"},"description":"Filter by post origin. \"late\" for posts published via Zernio, \"external\" for posts imported from platforms."}],"responses":{"200":{"description":"Posting frequency data","content":{"application/json":{"schema":{"type":"object","properties":{"frequency":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","example":"instagram"},"posts_per_week":{"type":"integer","description":"Number of posts published that week"},"avg_engagement_rate":{"type":"number","description":"Average engagement rate as percentage (0-100)"},"avg_engagement":{"type":"number","description":"Average raw engagement (likes+comments+shares+saves)"},"weeks_count":{"type":"integer","description":"Number of calendar weeks observed at this frequency"}}}}}},"examples":{"success":{"value":{"frequency":[{"platform":"instagram","posts_per_week":2,"avg_engagement_rate":44.4,"avg_engagement":512,"weeks_count":18},{"platform":"instagram","posts_per_week":4,"avg_engagement_rate":5.9,"avg_engagement":203,"weeks_count":6},{"platform":"facebook","posts_per_week":3,"avg_engagement_rate":12.5,"avg_engagement":87,"weeks_count":10}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Analytics add-on required"},"requiresAddon":{"type":"boolean","example":true}}}}}},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"}}}},"/v1/ledger/balances":{"get":{"x-resource-group":"money","operationId":"getLedgerBalances","tags":["Ledger"],"summary":"Get ledger balances","description":"Returns the balance of each bucket (for example accruing, owed, payable) for one ledger scope.\n\nThese return an empty balances object:\n\n- A scope owned by another team.\n- For a profile-scoped key (or a member limited to some profiles), any scope other than `campaign` and `participant` scopes of campaigns under its profiles.\n","parameters":[{"name":"scopeType","in":"query","required":true,"schema":{"type":"string"},"description":"Scope type, for example participant or campaign."},{"name":"scopeId","in":"query","required":true,"schema":{"type":"string"},"description":"Scope identifier."},{"name":"currency","in":"query","schema":{"type":"string","default":"usd"},"description":"Lowercase ISO 4217 currency code."}],"responses":{"200":{"description":"Balances per bucket in cents","content":{"application/json":{"schema":{"type":"object","properties":{"scopeType":{"type":"string"},"scopeId":{"type":"string"},"currency":{"type":"string"},"balances":{"type":"object","additionalProperties":{"type":"integer"},"description":"Bucket name to balance in cents (credits minus debits)"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"}}}},"/v1/ledger/entries":{"get":{"x-resource-group":"money","operationId":"listLedgerEntries","tags":["Ledger"],"summary":"List ledger entries","description":"Lists ledger entries for your team, newest first.\n\n### Filters\n\n- scope (matches either side of the entry)\n- kind\n- the reference that caused the entry\n\n### Profile-scoped access\n\nA profile-scoped key (or a member limited to some profiles) only sees entries of campaigns under its profiles and of their participants. Operator and platform scopes stay hidden from it.\n","parameters":[{"name":"scopeType","in":"query","schema":{"type":"string"}},{"name":"scopeId","in":"query","schema":{"type":"string"}},{"name":"kind","in":"query","schema":{"type":"string","enum":["accrual","approval","hold_release","adjustment","settling","settlement","reversal","topup","transfer","fee","usage","grant"]}},{"name":"referenceType","in":"query","schema":{"type":"string"}},{"name":"referenceId","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"skip","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Ledger entries","content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["accrual","approval","hold_release","adjustment","settling","settlement","reversal","topup","transfer","fee","usage","grant"]},"amountCents":{"type":"integer","description":"Always positive; direction is given by debit and credit"},"debit":{"$ref":"#/components/schemas/LedgerAccountSide"},"credit":{"$ref":"#/components/schemas/LedgerAccountSide"},"holdUntil":{"type":["string","null"],"format":"date-time"},"releasedByEntryId":{"type":["string","null"]},"referenceType":{"type":["string","null"]},"referenceId":{"type":["string","null"]},"reversesEntryId":{"type":["string","null"]},"cause":{"type":"string"},"actor":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"skip":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"}}}},"/v1/balance":{"get":{"x-resource-group":"money","operationId":"getBalance","tags":["Treasury"],"summary":"Get balance","description":"Returns your team's balance:\n\n- the balance you can transfer\n- the part of it that cannot be paid out to creators yet (`payoutLockedCents`, `payoutLocks`)\n- top-ups still waiting for payment\n- your latest top-ups\n\nA card top-up is in `availableCents` as soon as it is paid. Transfers to payees can use it from 7 days after the charge, so a stolen card cannot be turned straight into payouts.\n\nA transfer debits its amount plus the fee added on top; the payee receives the full amount.\n\nA card dispute or refund on a top-up is debited from the available balance and can make it negative. Transfers are refused until it is positive again.\n\nA profile-scoped key answers 403, since the balance belongs to the whole team.\n","responses":{"200":{"description":"Balance in cents","content":{"application/json":{"schema":{"type":"object","properties":{"availableCents":{"type":"integer","description":"Your balance, including card top-ups paid in the last 7 days (see payoutLockedCents). It goes negative after a dispute or refund of a spent top-up, or when pay-per-use already in flight lands past zero. The next top-up covers it. Transfers are refused while it is negative."},"promoCents":{"type":"integer","description":"Balance billing only (absent otherwise). Promotional and support credit Zernio added to your balance. Pay-per-use spends it before availableCents. It is never paid out to payees and is not part of availableCents."},"payoutLockedCents":{"type":"integer","description":"Part of availableCents from card top-ups charged in the last 7 days, net of refunds and disputes. Transfers to payees cannot use it yet; a transfer that needs it answers 409 `payout_funds_locked` with the day it can be sent."},"payoutLocks":{"type":"array","description":"The card top-ups behind payoutLockedCents, soonest first.","items":{"type":"object","required":["topupId","amountCents","chargedAt","unlocksAt"],"properties":{"topupId":{"type":"string"},"amountCents":{"type":"integer"},"chargedAt":{"type":"string","format":"date-time"},"unlocksAt":{"type":"string","format":"date-time","description":"From this time transfers can use it: 7 days after the charge."}}}},"pendingCents":{"type":"integer","description":"Card top-ups paid before 2026-10-29 that were held and are moving to availableCents (within the hour). Always 0 after that."},"pendingReleases":{"type":"array","description":"The held card top-ups behind pendingCents.","items":{"type":"object","required":["topupId","amountCents","availableAt"],"properties":{"topupId":{"type":"string"},"amountCents":{"type":"integer","description":"Net amount that moves to availableCents."},"availableAt":{"type":"string","format":"date-time"}}}},"pendingTopupCents":{"type":"integer","description":"Top-ups started but not paid yet."},"currency":{"type":"string","enum":["usd"]},"recentTopups":{"type":"array","items":{"$ref":"#/components/schemas/TreasuryTopup"}}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"}}}},"/v1/balance/auto-recharge":{"get":{"x-resource-group":"money","operationId":"getAutoRecharge","tags":["Treasury"],"summary":"Get auto-recharge settings","description":"Your balance's auto-recharge rule: when the balance drops below `belowCents`, the billing owner's saved card is charged back up to `toCents`, tax added on top as for any top-up.\n\nThe first read gives the default rule, sized from your last 30 days of pay-per-use: below about a week of spend (at least $5), back up by about two more weeks (at least $20).\n\n- 409 `balance_billing_required`: the account is not on the prepaid balance.\n\nA profile-scoped key answers 403.\n","responses":{"200":{"description":"Auto-recharge settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutoRecharge"}}}},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"},"409":{"description":"Code `balance_billing_required`: the account is not on the prepaid balance."}}},"patch":{"x-resource-group":"money","operationId":"updateAutoRecharge","tags":["Treasury"],"summary":"Update auto-recharge settings","description":"Changes the auto-recharge rule. Omitted fields keep their value.\n\nA declined recharge is retried 1 hour, 1 day and 3 days later, with an email each time. After the last retry fails, auto-recharge switches off (`disabledReason: payment_failed`) until the card is updated. A top-up you make yourself resets the retries.\n\nA bank asking for 3D Secure counts as a decline: the charge happens while you are away, so the email asks you to top up in Billing.\n\nWhen this month's auto-recharges plus the next one would pass `monthlyLimitCents`, the card is not charged and you get one email that month. At $0, pay-per-use then answers 402 `usage_limit_reached`.\n\n- 400: a field is out of range, or `toCents` is not more than $5 above `belowCents`.\n- 409 `balance_billing_required`: the account is not on the prepaid balance.\n\nNeeds an owner, admin or billing admin, signed in or through a full-access key they created.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","description":"Turns auto-recharge on or off. A rule switched off by failed charges stays off until the card is updated."},"belowCents":{"type":"integer","minimum":500,"maximum":10000000,"description":"Recharge when the balance drops below this, in cents. At least $5."},"toCents":{"type":"integer","minimum":500,"maximum":10000000,"description":"Recharge back up to this, in cents. More than $5 above belowCents."},"monthlyLimitCents":{"type":["integer","null"],"minimum":500,"maximum":10000000,"description":"Most auto-recharge may add per calendar month (UTC), before tax. Null for no limit."},"alertBelowCents":{"type":["integer","null"],"minimum":0,"maximum":10000000,"description":"Email the billing owner once each time the balance drops below this. Null for no email."}}}}}},"responses":{"200":{"description":"Updated settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutoRecharge"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"},"409":{"description":"Code `balance_billing_required`: the account is not on the prepaid balance."}}}},"/v1/balance/top-ups":{"post":{"x-resource-group":"money","operationId":"createTopup","tags":["Treasury"],"summary":"Create a top-up","description":"Charges the billing owner's saved card (the default one, or `paymentMethodId`) `amountCents` plus tax, while the payer is present, and credits your balance `amountCents`. There is no card fee.\n\nTax is added on top of the amount (`taxCents`, `totalCents`): VAT at 21% in Spain, at the customer's country rate for EU consumers; an EU business with a valid VAT id is reverse charged (no VAT, `reverseCharge: true`); outside the EU there is none.\n\nUsage paid from the balance carries no further VAT. Get the figures before paying with `POST /v1/balance/top-ups/preview`.\n\nEach top-up has an invoice, with VAT where it applies (`GET /v1/balance/top-ups/{topupId}/invoice`), and a card receipt (`GET /v1/balance/top-ups/{topupId}/receipt`).\n\n- `status: succeeded`: the card was charged. `amountCents` is credited to `availableCents` within seconds. Transfers to payees can use it from 7 days after the charge.\n- `status: requires_action`: the bank asked for 3D Secure. Complete it with Stripe.js `handleNextAction({ clientSecret })`, then call `POST /v1/balance/top-ups/{topupId}/confirm`. One left unconfirmed is cancelled after 30 minutes.\n\n### Errors\n\n- 402 `payment_required`: no saved card.\n- 402 `card_declined`: the bank's reason.\n- 400: `method: bank_transfer` (bank transfers are not available yet).\n- 400 `invalid_billing_address`: the billing address gives no tax location. Add it in Billing, then retry.\n\nNeeds an owner, admin or billing admin, signed in or through a full-access key they created.\n","parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amountCents","method"],"properties":{"amountCents":{"type":"integer","minimum":500,"maximum":10000000,"description":"Amount to credit to your balance, in cents: $5 to $100,000. Tax is charged on top; no card fee."},"method":{"type":"string","enum":["card","bank_transfer"],"description":"Only card is available. bank_transfer returns 400 \"Bank transfers are not available yet.\""},"paymentMethodId":{"type":"string","description":"A saved card of the billing owner's (`pm_...`). Defaults to the default payment method."}}}}}},"responses":{"201":{"description":"The card was charged, or the bank asked for 3D Secure","content":{"application/json":{"schema":{"type":"object","required":["topupId","status","clientSecret","amountCents","taxCents","totalCents","taxLabel","reverseCharge","feeCents","chargedCents","feeIsExact"],"properties":{"topupId":{"type":"string"},"amountCents":{"type":"integer","description":"Credited to your balance once paid."},"taxCents":{"type":"integer","description":"Tax added on top of amountCents (VAT where it applies). 0 when reverse charged or outside the EU."},"totalCents":{"type":"integer","description":"What the card is charged: amountCents + taxCents."},"taxLabel":{"type":["string","null"],"description":"The tax and its rate, for example \"VAT 21%\". Null when no tax is charged."},"reverseCharge":{"type":"boolean","description":"True for an EU business with a valid VAT id: no VAT is charged and the invoice says reverse charge."},"feeCents":{"type":"integer","description":"Always 0: there is no card fee. Kept for older clients."},"chargedCents":{"type":"integer","description":"Same as totalCents. Kept for older clients."},"feeIsExact":{"type":"boolean","description":"Always true. Kept for older clients."},"status":{"type":"string","enum":["succeeded","processing","requires_action"]},"clientSecret":{"type":["string","null"],"description":"PaymentIntent client secret for Stripe.js handleNextAction; set only when status is requires_action"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"x-summary":"The top-up failed because there is no saved card or the bank declined the charge: fix the payment method and retry.","description":"No saved card (code `payment_required`), or the bank declined the charge (code `card_declined`, the message is the reason), or a billing gate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/MoneyForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/IdempotencyKeyInFlight"},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"}}},"get":{"x-resource-group":"money","operationId":"listTopups","tags":["Treasury"],"summary":"List top-ups","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"skip","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Top-ups, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"topups":{"type":"array","items":{"$ref":"#/components/schemas/TreasuryTopup"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"}}}},"/v1/balance/top-ups/preview":{"post":{"x-resource-group":"money","operationId":"previewTopup","tags":["Treasury"],"summary":"Preview a top-up's tax","description":"The tax a top-up of `amountCents` will carry and the total the card is charged, calculated by Stripe Tax from the billing owner's billing address and tax ids, as the top-up's invoice will be. Charges nothing.\n\n- 400 `invalid_billing_address`: the billing address gives no tax location, so a top-up would be refused too.\n\nNeeds a full-access key or a signed-in session; a profile-scoped key answers 403.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amountCents"],"properties":{"amountCents":{"type":"integer","minimum":500,"maximum":10000000,"description":"Amount to credit to your balance, in cents."}}}}}},"responses":{"200":{"description":"Tax and total for the amount","content":{"application/json":{"schema":{"type":"object","required":["amountCents","taxCents","totalCents","taxLabel","reverseCharge"],"properties":{"amountCents":{"type":"integer","description":"Credited to your balance."},"taxCents":{"type":"integer","description":"Tax added on top (VAT where it applies)."},"totalCents":{"type":"integer","description":"What the card would be charged: amountCents + taxCents."},"taxLabel":{"type":["string","null"],"description":"The tax and its rate, for example \"VAT 21%\". Null when no tax is charged."},"reverseCharge":{"type":"boolean","description":"True for an EU business with a valid VAT id: no VAT, reverse charge."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"}}}},"/v1/balance/top-ups/{topupId}/receipt":{"get":{"x-resource-group":"money","operationId":"getTopupReceipt","tags":["Treasury"],"summary":"Get a top-up receipt","description":"The receipt for a paid top-up or creator payout payment (`purpose: payout_batch`). `url` is the payment's invoice PDF when it has one (`format: pdf`), else Stripe's card receipt page (`format: page`); `invoiceUrl` and `receiptUrl` give each on its own.\n\nThe invoice alone is at getTopupInvoice. The link is short-lived, so fetch it when you need it. A profile-scoped key answers 403.","parameters":[{"name":"topupId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Receipt link","content":{"application/json":{"schema":{"type":"object","required":["url","format","amountCents","feeCents","chargedCents"],"properties":{"url":{"type":"string","format":"uri"},"format":{"type":"string","enum":["pdf","page"]},"invoiceUrl":{"type":["string","null"],"format":"uri","description":"The invoice PDF; null when the payment made no invoice."},"receiptUrl":{"type":["string","null"],"format":"uri","description":"Stripe's card receipt page for the charge."},"amountCents":{"type":"integer","description":"As in the top-up list."},"feeCents":{"type":["integer","null"],"description":"Card fee paid, as in the top-up list."},"taxCents":{"type":"integer","description":"Tax charged on top of amountCents, as in the top-up list."},"chargedCents":{"type":"integer","description":"What the card was charged, tax included: the total on the receipt."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/balance/top-ups/{topupId}/invoice":{"get":{"x-resource-group":"money","operationId":"getTopupInvoice","tags":["Treasury"],"summary":"Get a top-up invoice","description":"The invoice for a paid balance top-up: the PDF of the Stripe invoice it was paid through.\n\nIt shows the amount added to your balance and the tax charged on top: VAT where it applies, or a reverse charge note for an EU business with a valid VAT id. Usage paid from the balance carries no further VAT.\n\n- `format: pdf` is the invoice PDF; `format: page` is its Stripe-hosted page when the PDF is not ready.\n- 404 before the top-up is paid, and for a payment with no invoice (top-ups before 2026-11-05, creator payout payments). Its card receipt is at getTopupReceipt.\n\nThe link is short-lived, so fetch it when you need it. A profile-scoped key answers 403.\n","parameters":[{"name":"topupId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Invoice link","content":{"application/json":{"schema":{"type":"object","required":["url","format","pdfUrl","pageUrl","amountCents","taxCents","chargedCents"],"properties":{"url":{"type":"string","format":"uri"},"format":{"type":"string","enum":["pdf","page"]},"pdfUrl":{"type":["string","null"],"format":"uri","description":"The invoice PDF."},"pageUrl":{"type":["string","null"],"format":"uri","description":"The invoice's Stripe-hosted page."},"amountCents":{"type":"integer","description":"Amount added to your balance, as in the top-up list."},"taxCents":{"type":"integer","description":"Tax charged on top of amountCents."},"chargedCents":{"type":"integer","description":"What the card was charged, tax included."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/balance/top-ups/{topupId}/statement":{"get":{"x-resource-group":"money","operationId":"getTopupStatement","tags":["Treasury"],"summary":"Get a top-up invoice (alias)","deprecated":true,"description":"Alias of getTopupInvoice, kept for clients written against its first name.\n\nThe invoice for a paid balance top-up: the PDF of the Stripe invoice it was paid through.\n\nIt shows the amount added to your balance and the tax charged on top: VAT where it applies, or a reverse charge note for an EU business with a valid VAT id. Usage paid from the balance carries no further VAT.\n\n- `format: pdf` is the invoice PDF; `format: page` is its Stripe-hosted page when the PDF is not ready.\n- 404 before the top-up is paid, and for a payment with no invoice (top-ups before 2026-11-05, creator payout payments). Its card receipt is at getTopupReceipt.\n\nThe link is short-lived, so fetch it when you need it. A profile-scoped key answers 403.\n","parameters":[{"name":"topupId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Invoice link","content":{"application/json":{"schema":{"type":"object","required":["url","format","pdfUrl","pageUrl","amountCents","taxCents","chargedCents"],"properties":{"url":{"type":"string","format":"uri"},"format":{"type":"string","enum":["pdf","page"]},"pdfUrl":{"type":["string","null"],"format":"uri","description":"The invoice PDF."},"pageUrl":{"type":["string","null"],"format":"uri","description":"The invoice's Stripe-hosted page."},"amountCents":{"type":"integer","description":"Amount added to your balance, as in the top-up list."},"taxCents":{"type":"integer","description":"Tax charged on top of amountCents."},"chargedCents":{"type":"integer","description":"What the card was charged, tax included."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/balance/top-ups/{topupId}/confirm":{"post":{"x-resource-group":"money","operationId":"confirmTopup","tags":["Treasury"],"summary":"Confirm a top-up","description":"Call after 3D Secure. Reads the payment from Stripe, then:\n\n- `succeeded`: paid, the top-up is credited.\n- `failed`: the bank refused it.\n- `pending`: Stripe is still settling the charge.\n\nSafe to repeat. Needs an owner, admin or billing admin, signed in or through a full-access key they created.\n","parameters":[{"name":"topupId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The top-up after confirming","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TreasuryTopup"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/MoneyForbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/balance/top-ups/{topupId}/cancel":{"post":{"x-resource-group":"money","operationId":"cancelTopup","tags":["Treasury"],"summary":"Cancel a top-up","description":"Ends the payment of a pending top-up (3D Secure left unfinished), so it stops counting toward `pendingTopupCents`, and returns it as `expired`.\n\n- When Stripe reports it already paid, the top-up is credited and comes back `succeeded`.\n- A top-up that is no longer pending comes back unchanged.\n- A creator payout payment (`purpose: payout_batch`) answers 409; cancel it from its campaign.\n\nNeeds an owner, admin or billing admin, signed in or through a full-access key they created.\n","parameters":[{"name":"topupId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The top-up after cancelling","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TreasuryTopup"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/MoneyForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The top-up is a creator payout payment (code `invalid_resource_state`); cancel it from its campaign.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/payees":{"get":{"x-resource-group":"money","operationId":"listPayees","tags":["Treasury"],"summary":"List payees","description":"Payees you can transfer to. A payee can receive transfers once `payoutsEnabled` is true. A profile-scoped key answers 403.","responses":{"200":{"description":"Payees","content":{"application/json":{"schema":{"type":"object","properties":{"payees":{"type":"array","items":{"$ref":"#/components/schemas/TreasuryPayee"}}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"}}}},"/v1/payees/{payeeId}/onboarding-link":{"post":{"x-resource-group":"money","operationId":"createPayeeOnboardingLink","tags":["Treasury"],"summary":"Create a payee onboarding link","description":"Returns a Stripe-hosted link where the payee completes identity and bank details so they can receive payouts.","parameters":[{"name":"payeeId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Onboarding link","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/transfers":{"post":{"x-resource-group":"money","operationId":"createTransfer","tags":["Treasury"],"summary":"Create a transfer","description":"Moves money from your balance to a payee.\n\n### Fee\n\nThe payee receives the full `amountCents`. Zernio's fee (4%, 50 cent minimum) is added on top, so your balance is debited `totalCents` = `amountCents` + `feeCents`.\n\n### Who can call it\n\nNeeds an owner, admin or billing admin, signed in or through a full-access key they created. A profile-scoped key answers 403.\n\n### Errors\n\n- 402: the balance does not cover the amount plus the fee.\n- 402: the balance is negative after a dispute or refund of a card top-up (\"Your balance is negative after a dispute or refund of a card top-up. Add funds to cover it before sending transfers.\").\n- 409: the payee has not finished onboarding, or the Idempotency-Key is still processing.\n- 409 `payout_funds_locked`: money from a card top-up can be transferred from 7 days after the charge. The message names the amount and the day (\"$100.00 from your card top-up on Oct 29 can be paid out from Nov 5.\").\n\n### Retries\n\nA same-key retry never makes the transfer twice within Stripe's 24-hour idempotency window. It answers 409 while another request is still waiting on Stripe for it.\n\nA transfer Stripe has not confirmed after 24 hours answers 409 until the daily reconciliation marks it paid (Stripe made it) or failed (it did not).\n","parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payeeId","amountCents"],"properties":{"payeeId":{"type":"string","minLength":24,"maxLength":24,"description":"24-character payee id"},"amountCents":{"type":"integer","minimum":1,"description":"Amount the payee receives, in cents. The fee is added on top."},"reference":{"type":"object","required":["type","id"],"properties":{"type":{"type":"string"},"id":{"type":"string"}}}}}}}},"responses":{"201":{"description":"Transfer created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TreasuryTransfer"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/MoneyForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"x-summary":"The transfer cannot proceed yet because payout onboarding is unfinished or the request is still processing: wait and retry later.","description":"Payee has not finished payout onboarding, the Idempotency-Key is still processing, another request is waiting on Stripe for this transfer, or Stripe has not confirmed it within 24 hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"}}},"get":{"x-resource-group":"money","operationId":"listTransfers","tags":["Treasury"],"summary":"List transfers","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"skip","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Transfers, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"transfers":{"type":"array","items":{"$ref":"#/components/schemas/TreasuryTransfer"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"}}}},"/v1/transfers/{transferId}":{"get":{"x-resource-group":"money","operationId":"getTransfer","tags":["Treasury"],"summary":"Get a transfer","parameters":[{"name":"transferId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Transfer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TreasuryTransfer"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/public/creator-campaigns/recover-link":{"post":{"x-resource-group":"public","operationId":"recoverCreatorPortalLinks","tags":["Creator Portal"],"summary":"Email a creator their campaign links","security":[],"description":"For a creator who lost their link. Emails every personal participant link held by `email` in one message, optionally only the one for `campaignId`.\n\n- Removed participants and draft campaigns are left out.\n- Always answers 202 with the same body, so the answer never tells whether the address has links.\n- Limited to 5 requests per hour per email address and 5 per hour per IP address.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","maxLength":320},"campaignId":{"type":"string","description":"Only send the link for this campaign."}}}}}},"responses":{"202":{"x-summary":"The request was accepted: if the address has links, they are on their way.","description":"Accepted. If the address has links, they are on their way.","content":{"application/json":{"schema":{"type":"object","required":["status","message"],"properties":{"status":{"type":"string","enum":["accepted"]},"message":{"type":"string"}}}}}},"400":{"description":"The email is missing or not a valid address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"$ref":"#/components/responses/CreatorPortalRateLimited"}}}},"/public/creator-campaigns/{token}":{"parameters":[{"$ref":"#/components/parameters/CreatorPortalToken"}],"get":{"x-resource-group":"public","operationId":"getCreatorPortal","tags":["Creator Portal"],"summary":"Read a creator invite or participant page","security":[],"description":"What a creator sees behind a campaign link, with no API key. Never cached.\n\n`token` is one of:\n\n- An open invite token (from `POST /v1/creator-campaigns/{campaignId}/invite-link`): answers `kind: invite` with the campaign only.\n- A participant token (from an invite or a join): answers `kind: participant` with the creator's connected accounts, latest 100 submissions, earnings and payout setup.\n\nReading a participant page also re-checks the creator's connected accounts.\n","responses":{"200":{"description":"The invite or participant page.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CreatorPortalInvite"},{"$ref":"#/components/schemas/CreatorPortalParticipant"}],"discriminator":{"propertyName":"kind","mapping":{"invite":"#/components/schemas/CreatorPortalInvite","participant":"#/components/schemas/CreatorPortalParticipant"}}}}}},"404":{"$ref":"#/components/responses/CreatorPortalLinkNotFound"}}},"post":{"x-resource-group":"public","operationId":"joinCreatorCampaign","tags":["Creator Portal"],"summary":"Join a campaign","security":[],"description":"Accepts a participant invite, or joins through an open invite link.\n\n- Participant token: the body is ignored and the invite is accepted.\n- Open invite token: a new participant is created from `displayName` (required) and `email` (optional), and a fresh participant token comes back. Keep it: it is the creator's only key to their page.\n\nOpen-link joins are limited to about 20 per IP address and 60 per link every 10 minutes.\n","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"type":"string","minLength":1,"maxLength":200,"description":"Required when joining through an open invite link."},"email":{"type":"string","format":"email"}}}}}},"responses":{"201":{"x-summary":"The creator joined the campaign: use the returned `participantToken` for every later call.","description":"Joined. Use `participantToken` for every later call.","content":{"application/json":{"schema":{"type":"object","required":["participantToken"],"properties":{"participantToken":{"type":"string"}}}}}},"400":{"x-summary":"The join request is invalid, such as a missing display name or an ended campaign: fix the request and retry.","description":"Missing `displayName` on an open-link join (\"Add your name to join.\", `missing_required_field`), an invalid field, or the campaign has ended (`invalid_resource_state`, \"This campaign has ended.\").","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"x-summary":"The campaign is not taking new creators right now, for example because it reached its participant cap: ask the campaign team.","description":"The campaign is not taking new creators (`feature_not_available`, \"This campaign is not taking new creators right now. Ask the campaign team.\"), for example because it reached its participant cap.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/CreatorPortalLinkNotFound"},"429":{"$ref":"#/components/responses/CreatorPortalRateLimited"}}}},"/public/creator-campaigns/{token}/connect":{"parameters":[{"$ref":"#/components/parameters/CreatorPortalToken"}],"post":{"x-resource-group":"public","operationId":"startCreatorConnect","tags":["Creator Portal"],"summary":"Start connecting a creator account","security":[],"description":"Returns the authorization URL that connects one of the creator's own social accounts,\nread-only, so their posts can be verified. Send the creator's browser to `authUrl`; they\ncome back to their participant page. Only the campaign's platforms are accepted.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform"],"properties":{"platform":{"type":"string","minLength":1,"maxLength":40,"description":"One of the campaign's platforms, for example tiktok."}}}}}},"responses":{"200":{"description":"Authorization URL.","content":{"application/json":{"schema":{"type":"object","required":["authUrl"],"properties":{"authUrl":{"type":"string","format":"uri"}}}}}},"400":{"x-summary":"The connect request is invalid because the platform is not in the campaign, the account limit is reached, or the campaign ended.","description":"The platform is not part of the campaign (`invalid_field_value`), the campaign allows no more connected accounts (\"This campaign allows N connected accounts.\"), or the campaign has ended (`invalid_resource_state`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/CreatorPortalLinkNotFound"},"409":{"description":"The creator's participation was suspended or removed (`invalid_resource_state`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/public/creator-campaigns/{token}/submissions":{"parameters":[{"$ref":"#/components/parameters/CreatorPortalToken"}],"post":{"x-resource-group":"public","operationId":"submitCreatorPost","tags":["Creator Portal"],"summary":"Submit a post","security":[],"description":"Submits the link to a post the creator published from a connected account. The post opens\na tracking window and fires `campaign_submission.received` to the operator. About 30\nattempts and 10 accepted posts per participant every 10 minutes.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","minLength":1,"maxLength":2048,"description":"The public link to the post."}}}}}},"responses":{"201":{"description":"Submitted.","content":{"application/json":{"schema":{"type":"object","required":["submission"],"properties":{"submission":{"$ref":"#/components/schemas/CreatorPortalSubmission"}}}}}},"400":{"x-summary":"The post is refused: submit an accepted platform post made within the campaign window, from one of the creator's allowed accounts.","description":"The post cannot be submitted: 400 `invalid_field_value`.\n\n- `param: url`: the link is not a post of an accepted platform, or the post was published before the campaign started or longer ago than the campaign accepts.\n- TikTok and X post ids carry their creation time, so a post from before the campaign is refused as such even when no connected account has it.\n- The post is from an account past the campaign's `caps.maxAccountsPerParticipant` (\"This campaign allows 2 connected accounts.\"). Only the first accounts the creator connected, up to that count, can submit.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"x-summary":"The creator has not connected an account on that platform yet: connect it first, then submit the post again.","description":"The creator has not connected an account on that platform yet (`insufficient_permissions`, \"Connect your TikTok account first, then submit the post again\").","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"x-summary":"The link is invalid or expired, or no connected account has the post yet: check the link and retry.","description":"The link is invalid or expired, or no connected account has the post (`resource_not_found`, `param: url`).\n\n- When the link names its author (TikTok, Instagram, Threads, X) and that is not one of the creator's accounts, the message names both handles.\n- Otherwise it says the post was not found yet, for example because it was published moments ago.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"x-summary":"The post cannot be submitted: accept the invite, wait for an active campaign, and submit each post once within the daily limit.","description":"The invite is not accepted yet, the campaign is not accepting posts (not started, paused or ended), the post was already submitted, today's per-participant post limit is reached, or the participation was suspended or removed (`invalid_resource_state`; the message says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"$ref":"#/components/responses/CreatorPortalRateLimited"}}}},"/public/creator-campaigns/{token}/accounts/{accountId}":{"parameters":[{"$ref":"#/components/parameters/CreatorPortalToken"},{"name":"accountId","in":"path","required":true,"description":"The `id` of one of the participant's `accounts`.","schema":{"type":"string"}}],"delete":{"x-resource-group":"public","operationId":"removeCreatorAccount","tags":["Creator Portal"],"summary":"Remove a connected account","security":[],"description":"Disconnects one of the creator's accounts. The account belongs to the creator, not to one campaign, so it stops\ncounting in every campaign of this brand they joined.\n\nWhat its posts already earned stays: accrued, approved and paid amounts are not touched.\n\nRefused while a post from the account is still counting views, because those views are read through the\naccount. It can be removed once their tracking ends.\n","responses":{"200":{"description":"Removed.","content":{"application/json":{"schema":{"type":"object","required":["removed"],"properties":{"removed":{"type":"boolean","description":"Always true."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"The link is invalid or expired, or the account is not one of the participant's accounts on the campaign's platforms (`resource_not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"A post from the account is still counting views (`invalid_resource_state`; the message says how many).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/public/creator-campaigns/{token}/payouts":{"parameters":[{"$ref":"#/components/parameters/CreatorPortalToken"}],"get":{"x-resource-group":"public","operationId":"getCreatorPayouts","tags":["Creator Portal"],"summary":"List a creator's earnings history","security":[],"description":"The participant's ledger entries, newest first, with the bucket each one moved money\nfrom and to (`accruing`, `owed`, `payable`, `settling`, `settled`; null for the other\nside), plus the payout setup. Never cached.\n","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"skip","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Earnings history and payout setup.","content":{"application/json":{"schema":{"type":"object","required":["entries","total","payouts"],"properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/CreatorPortalPayoutEntry"}},"total":{"type":"integer"},"payouts":{"$ref":"#/components/schemas/CreatorPortalPayoutSetup"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/CreatorPortalLinkNotFound"}}},"post":{"x-resource-group":"public","operationId":"startCreatorPayouts","tags":["Creator Portal"],"summary":"Start payout onboarding","security":[],"description":"For a campaign that pays through the Zernio treasury: creates the creator's payee on first\nuse and returns a Stripe-hosted onboarding link where they enter identity and bank\ndetails. `country` is required the first time and cannot change afterwards. About 20\nattempts per participant every 10 minutes.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["onboard"]},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2 country the creator lives in. Required on the first call."}}}}}},"responses":{"200":{"description":"Stripe onboarding link.","content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"400":{"x-summary":"The payout country is missing on the first call or differs from the saved one: send the correct country.","description":"`country` is missing on the first call (\"Choose the country you live in.\") or differs from the one already saved (\"Payout country cannot be changed.\").","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/CreatorPortalLinkNotFound"},"409":{"description":"The campaign team pays the creator directly, so there is nothing to set up (`invalid_resource_state`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"$ref":"#/components/responses/CreatorPortalRateLimited"}}}},"/public/creator-campaigns/{token}/payout-login":{"parameters":[{"$ref":"#/components/parameters/CreatorPortalToken"}],"post":{"x-resource-group":"public","operationId":"createCreatorPayoutLogin","tags":["Creator Portal"],"summary":"Open the creator's Stripe dashboard","security":[],"description":"Returns a one-time link into the creator's Stripe Express dashboard, where they change bank\ndetails and see each payout. Only after the creator submitted their payout details. About\n20 attempts per participant every 10 minutes.\n","responses":{"200":{"description":"Stripe login link.","content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"404":{"$ref":"#/components/responses/CreatorPortalLinkNotFound"},"409":{"x-summary":"The creator has not submitted payout details yet, or the team pays them directly: finish payout setup first.","description":"The creator has not submitted payout details yet, or the campaign team pays them directly (\"Finish payout setup first.\", `invalid_resource_state`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"$ref":"#/components/responses/CreatorPortalRateLimited"}}}},"/public/creator-campaigns/{token}/payouts/{transferId}/statement":{"parameters":[{"$ref":"#/components/parameters/CreatorPortalToken"},{"name":"transferId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"x-resource-group":"public","operationId":"getCreatorPayoutStatement","tags":["Creator Portal"],"summary":"Download a payout statement","security":[],"description":"A PDF statement of one paid payout to this creator: who paid, the campaign, the date, the amount and the Stripe transfer id. It is a statement of a payment, not a tax invoice.\n\nOnly for a paid payout of this participant; anything else answers 404.\n\nAbout 60 downloads per participant every 10 minutes.\n","responses":{"200":{"description":"The statement, as an attachment.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"The link is invalid, or no paid payout of this participant has this id (\"Payout not found.\").","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"$ref":"#/components/responses/CreatorPortalRateLimited"}}}},"/v1/payout-batches/{batchId}":{"get":{"x-resource-group":"money","operationId":"getPayoutBatch","tags":["Treasury"],"summary":"Get a payout batch","description":"One payout batch with its status and each creator's item. Poll it after the card payment to see when every creator is paid.","security":[{"bearerAuth":[]}],"parameters":[{"name":"batchId","in":"path","required":true,"schema":{"type":"string"},"description":"Payout batch ID."}],"responses":{"200":{"description":"The payout batch.","content":{"application/json":{"schema":{"type":"object","required":["batch"],"properties":{"batch":{"$ref":"#/components/schemas/PayoutBatch"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No payout batch with this id in a campaign you can see.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/payout-batches/{batchId}/confirm":{"post":{"x-resource-group":"money","operationId":"confirmPayoutBatch","tags":["Treasury"],"summary":"Confirm a payout batch payment","description":"Call after 3D Secure. Reads the batch's payment from Stripe, then:\n\n- charge succeeded: pays the creators (`paying`, then `paid`).\n- bank refused: ends the batch (`failed`) and makes every amount payable again.\n- still settling: leaves it `awaiting_payment`.\n\nSafe to repeat. Needs an owner, admin or billing admin, signed in or through a full-access key they created.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"batchId","in":"path","required":true,"schema":{"type":"string"},"description":"Payout batch ID."}],"responses":{"200":{"description":"The payout batch after confirming.","content":{"application/json":{"schema":{"type":"object","required":["batch"],"properties":{"batch":{"$ref":"#/components/schemas/PayoutBatch"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MoneyForbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/payout-batches/{batchId}/cancel":{"post":{"x-resource-group":"money","operationId":"cancelPayoutBatch","tags":["Treasury"],"summary":"Cancel an unpaid payout batch","description":"Ends the payment of a batch that is still `awaiting_payment` (3D Secure left unfinished) and makes every amount payable again right away.\n\n- When Stripe reports the charge already made, the batch is paid out instead.\n- A batch that was already paid is returned unchanged.\n\nNeeds an owner, admin or billing admin, signed in or through a full-access key they created.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"batchId","in":"path","required":true,"schema":{"type":"string"},"description":"Payout batch ID."}],"responses":{"200":{"description":"The payout batch after the cancel.","content":{"application/json":{"schema":{"type":"object","required":["batch"],"properties":{"batch":{"$ref":"#/components/schemas/PayoutBatch"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MoneyForbidden"},"404":{"description":"No payout batch with this id in a campaign you can see.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/analytics/post-timeline":{"get":{"x-resource-group":"analytics","operationId":"getPostTimeline","tags":["Analytics"],"summary":"Get post analytics timeline","description":"Returns a daily timeline of analytics metrics for a specific post, showing how impressions, likes,\nand other metrics evolved day-by-day since publishing. Each row represents one day of data per platform.\nFor multi-platform Zernio posts, returns separate rows for each platform.\n","parameters":[{"name":"postId","in":"query","required":true,"schema":{"type":"string"},"description":"The post to fetch timeline for. Accepts an ExternalPost ID, a platformPostId, or a Zernio Post ID.\n"},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date-time"},"description":"Start of date range (ISO 8601). Defaults to 90 days ago."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date-time"},"description":"End of date range (ISO 8601). Defaults to now."}],"responses":{"200":{"description":"Daily analytics timeline","content":{"application/json":{"schema":{"type":"object","properties":{"postId":{"type":"string","description":"The postId that was requested"},"timeline":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date in YYYY-MM-DD format"},"platform":{"type":"string","description":"Platform name (e.g. instagram, tiktok)"},"platformPostId":{"type":"string","description":"Platform-specific post ID"},"impressions":{"type":"integer","description":"Total impressions on this date"},"reach":{"type":"integer","description":"Total reach on this date"},"likes":{"type":"integer","description":"Total likes on this date"},"comments":{"type":"integer","description":"Total comments on this date"},"shares":{"type":"integer","description":"Total shares on this date"},"saves":{"type":"integer","description":"Total saves on this date"},"clicks":{"type":"integer","description":"Total clicks on this date"},"views":{"type":"integer","description":"Total views on this date"},"follows":{"type":["integer","null"],"description":"Follows attributed to the post on this date (Instagram feed and stories, Facebook Reels, TikTok business lane). Null on Instagram Reels and video and on Facebook posts that are not Reels, where Meta has no follows metric; 0 on other platforms."},"completionRate":{"type":"number","description":"TikTok business lane: share of viewers who watched to the end on this date, 0 to 1; 0 elsewhere"},"profileViews":{"type":"integer","description":"Instagram feed posts (images and carousels; 0 on Reels and Stories) and TikTok business lane: profile views attributed to the post on this date; 0 elsewhere"},"websiteClicks":{"type":"integer","description":"TikTok business lane: website-link clicks attributed to the post on this date (also inside clicks); 0 elsewhere"},"impressionSources":{"type":"object","additionalProperties":{"type":"number"},"description":"TikTok business lane: share of views by surface on this date (forYou, follow, search, personalProfile, sound, directMessage, other), fractions 0 to 1; empty object elsewhere"},"audienceTypes":{"type":"object","additionalProperties":{"type":"number"},"description":"TikTok business lane: follower / nonFollower and newViewer / returnViewer shares on this date, fractions 0 to 1; empty object elsewhere"},"audienceCountries":{"type":"object","additionalProperties":{"type":"number"},"description":"TikTok business lane: viewer-country shares on this date keyed by ISO-3166 alpha-2, fractions 0 to 1, top 20 with the tail in `other`; empty object elsewhere"},"replays":{"type":"integer","description":"Facebook Reels only: plays that were replays, as of this date; 0 elsewhere"},"retentionCurve":{"type":"object","additionalProperties":{"type":"number"},"description":"Share of viewers still watching at each second of playback, as fractions 0 to 1. Filled for Facebook Reels and the TikTok business lane; empty object for other media and platforms. Values are as of this date.\n\n**Facebook Reels** (Meta post_video_retention_graph):\n\n- The base is a subset of plays that Meta selects and does not expose. On small Reels it can be far below views (6 of 51 measured), so a value is a share of that subset, not of all plays.\n- Keys are whole seconds from the start of a play (\"3\" is the share still watching at 3 s).\n- Loops count as continued playback, so a short Reels curve runs past its length (an 8 s Reel has keys \"0\" to \"12\").\n- Meta returns at most 41 points, so a long Reel covers only its first 40 s.\n\n**TikTok** accounts connected through the TikTok for Business app: from TikTok video_view_retention, at each whole second, at most 61 points, thinned evenly on videos longer than 60 s."}}}}}},"examples":{"single_platform":{"summary":"Single-platform post timeline","value":{"postId":"6507a1b2c3d4e5f6a7b8c9d0","timeline":[{"date":"2025-01-15","platform":"instagram","platformPostId":"17902345678901234","impressions":1200,"reach":980,"likes":45,"comments":3,"shares":12,"saves":8,"clicks":25,"views":0,"follows":2,"completionRate":0,"profileViews":0,"websiteClicks":0,"impressionSources":{},"audienceTypes":{},"audienceCountries":{}},{"date":"2025-01-16","platform":"instagram","platformPostId":"17902345678901234","impressions":2400,"reach":1850,"likes":92,"comments":7,"shares":21,"saves":15,"clicks":48,"views":0,"follows":5,"completionRate":0,"profileViews":0,"websiteClicks":0,"impressionSources":{},"audienceTypes":{},"audienceCountries":{}}]}},"multi_platform":{"summary":"One row per platform and day; the TikTok row comes from an account connected through the TikTok for Business app","value":{"postId":"6507a1b2c3d4e5f6a7b8c9d0","timeline":[{"date":"2025-01-16","platform":"instagram","platformPostId":"17902345678901234","impressions":2400,"reach":1850,"likes":92,"comments":7,"shares":21,"saves":15,"clicks":48,"views":0,"follows":5,"completionRate":0,"profileViews":0,"websiteClicks":0,"impressionSources":{},"audienceTypes":{},"audienceCountries":{}},{"date":"2025-01-16","platform":"tiktok","platformPostId":"7685731010461371662","impressions":0,"reach":1100,"likes":60,"comments":4,"shares":9,"saves":3,"clicks":14,"views":1320,"follows":3,"completionRate":0.18,"profileViews":22,"websiteClicks":6,"impressionSources":{"forYou":0.84,"follow":0.05,"search":0.06,"personalProfile":0.03,"sound":0.01,"directMessage":0,"other":0.01},"audienceTypes":{"follower":0.1,"nonFollower":0.9,"newViewer":0.99,"returnViewer":0.01},"audienceCountries":{"US":0.62,"GB":0.11,"CA":0.07,"DE":0.05,"other":0.15}}]}}}}}},"400":{"description":"Missing required postId parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Missing required parameter: postId"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Analytics add-on required"},"code":{"type":"string","example":"analytics_addon_required"}}}}}},"403":{"description":"Forbidden (post belongs to another user or API key scope violation)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Forbidden"}}}}}},"404":{"description":"Post not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Post not found"}}}}}},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"}}}},"/v1/analytics/googleanalytics/report":{"post":{"x-resource-group":"analytics","operationId":"runGoogleAnalyticsReport","tags":["Analytics"],"summary":"Run a Google Analytics (GA4) report","description":"Runs a report on a connected GA4 property through Google's Data API (`runReport`).\n\nPick any GA4 dimensions and metrics; filters and ordering use Google's own shapes.\n\n### Caching and quota\n\nIdentical requests on the same property are cached for 10 minutes.\n\nGoogle meters each property by quota tokens. When it is used up the request returns 429 until Google refills it (hourly quotas within the hour, daily ones at midnight Pacific time).\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GoogleAnalyticsReportFields"},{"type":"object","properties":{"dateRanges":{"type":"array","minItems":1,"maxItems":4,"description":"Defaults to the last 28 days (`28daysAgo` to `yesterday`).","items":{"type":"object","required":["startDate","endDate"],"properties":{"startDate":{"type":"string","description":"YYYY-MM-DD, today, yesterday or NdaysAgo.","example":"30daysAgo"},"endDate":{"type":"string","description":"YYYY-MM-DD, today, yesterday or NdaysAgo.","example":"today"},"name":{"type":"string"}}}},"offset":{"type":"integer","minimum":0,"description":"Row offset for paging through a report larger than `limit`."},"keepEmptyRows":{"type":"boolean"},"currencyCode":{"type":"string","description":"ISO 4217 code for currency metrics. Defaults to the property currency."}}}]},"example":{"accountId":"6650f1c2a1b2c3d4e5f60789","dateRanges":[{"startDate":"30daysAgo","endDate":"yesterday"}],"dimensions":["sessionDefaultChannelGroup"],"metrics":["sessions","activeUsers","keyEvents"],"orderBys":[{"metric":{"metricName":"sessions"},"desc":true}]}}}},"responses":{"200":{"description":"Report rows from Google","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleAnalyticsReport"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The Google account that connected the property lost access or revoked Zernio: reconnect Google Analytics.","description":"The Google account that connected the property lost access to it, or revoked Zernio. Reconnect Google Analytics."},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/analytics/googleanalytics/realtime":{"post":{"x-resource-group":"analytics","operationId":"runGoogleAnalyticsRealtimeReport","tags":["Analytics"],"summary":"Run a Google Analytics (GA4) realtime report","description":"Activity on a connected GA4 property in the last 30 minutes (up to 60 for Analytics 360),\nthrough Google's `runRealtimeReport`. Not cached. Only realtime dimensions and metrics are\naccepted, e.g. `country`, `unifiedScreenName` with `activeUsers`.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GoogleAnalyticsReportFields"},{"type":"object","properties":{"minuteRanges":{"type":"array","minItems":1,"maxItems":2,"items":{"type":"object","properties":{"startMinutesAgo":{"type":"integer","minimum":0,"maximum":59},"endMinutesAgo":{"type":"integer","minimum":0,"maximum":59},"name":{"type":"string"}}}}}}]},"example":{"accountId":"6650f1c2a1b2c3d4e5f60789","dimensions":["country"],"metrics":["activeUsers"]}}}},"responses":{"200":{"description":"Realtime report rows from Google","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleAnalyticsReport"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The Google account that connected the property lost access or revoked Zernio: reconnect Google Analytics.","description":"The Google account that connected the property lost access to it, or revoked Zernio. Reconnect Google Analytics."},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/analytics/googleanalytics/metadata":{"get":{"x-resource-group":"analytics","operationId":"getGoogleAnalyticsMetadata","tags":["Analytics"],"summary":"List Google Analytics (GA4) dimensions and metrics","description":"Every dimension and metric the connected GA4 property accepts in a report, including its\ncustom definitions. Cached for one hour.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio account ID of the Google Analytics connection."}],"responses":{"200":{"description":"Available dimensions and metrics","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"},"propertyId":{"type":"string"},"dimensions":{"type":"array","items":{"type":"object","properties":{"apiName":{"type":"string","example":"sessionSource"},"uiName":{"type":"string","example":"Session source"},"description":{"type":"string"},"category":{"type":"string"},"customDefinition":{"type":"boolean"}}}},"metrics":{"type":"array","items":{"type":"object","properties":{"apiName":{"type":"string","example":"sessions"},"uiName":{"type":"string","example":"Sessions"},"description":{"type":"string"},"type":{"type":"string","example":"TYPE_INTEGER"},"category":{"type":"string"},"customDefinition":{"type":"boolean"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The Google account that connected the property lost access or revoked Zernio: reconnect Google Analytics.","description":"The Google account that connected the property lost access to it, or revoked Zernio. Reconnect Google Analytics."},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/analytics/tracking":{"post":{"x-resource-group":"analytics","operationId":"openTrackingWindow","tags":["Analytics"],"x-platforms":["instagram","facebook","tiktok","youtube","twitter","threads","pinterest","reddit","bluesky","googlebusiness","linkedin"],"summary":"Open a tracking window","description":"Starts watching a post's views and engagement.\n\nZernio fetches the numbers from the platform itself on its regular analytics sync, so every reading is verified. It is a value we read from the platform, never one the creator or the caller reported.\n\n### The window\n\n- Runs for `trackingDays` (30 by default, 90 at most).\n- Ends with one final read, after which the `post.tracking_completed` webhook fires.\n\n### Identifying the post\n\nSend either `postId` (an external post id from Zernio), or `accountId` together with the post's `url`.\n\n### Responses\n\n- `201`: a new window was opened.\n- `200`: the post is already tracked; the existing window is returned.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"postId":{"type":"string","description":"Id of an external post. Required unless `accountId` and `url` are both sent."},"accountId":{"type":"string","description":"Connected account the post belongs to. Send together with `url`."},"url":{"type":"string","description":"Public URL of the post on the platform. Send together with `accountId`."},"trackingDays":{"type":"integer","minimum":1,"maximum":90,"default":30,"description":"How many days the window stays open."},"requestedBy":{"type":"string","default":"api","description":"Free-form label for who asked for the window. It is stored and returned as given."}}},"examples":{"byUrl":{"summary":"Track a post by account and URL","value":{"accountId":"6507a1b2c3d4e5f6a7b8c9d0","url":"https://www.tiktok.com/@creator/video/7685731010461371662","trackingDays":30}}}}}},"responses":{"200":{"description":"The post already had a window; it is returned unchanged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackingWindowResponse"}}}},"201":{"description":"Window opened","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackingWindowResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/AnalyticsAddonRequired"},"403":{"description":"API key scope violation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Post or account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"x-resource-group":"analytics","operationId":"listTrackingWindows","tags":["Analytics"],"x-platforms":["instagram","facebook","tiktok","youtube","twitter","threads","pinterest","reddit","bluesky","googlebusiness","linkedin"],"summary":"List tracking windows","description":"Lists the tracking windows you can see, newest first. Each window carries the latest verified\nnumbers we read from the platform.\n","parameters":[{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Only windows for this connected account."},{"name":"status","in":"query","schema":{"type":"string","enum":["open","completing","completed","cancelled"]},"description":"Only windows in this status."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Page size."},{"name":"skip","in":"query","schema":{"type":"integer","minimum":0,"default":0},"description":"Number of windows to skip."}],"responses":{"200":{"description":"Tracking windows","content":{"application/json":{"schema":{"type":"object","required":["windows"],"properties":{"windows":{"type":"array","items":{"$ref":"#/components/schemas/TrackingWindow"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/AnalyticsAddonRequired"},"403":{"description":"API key scope violation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"}}}},"/v1/analytics/tracking/{windowId}":{"get":{"x-resource-group":"analytics","operationId":"getTrackingWindow","tags":["Analytics"],"x-platforms":["instagram","facebook","tiktok","youtube","twitter","threads","pinterest","reddit","bluesky","googlebusiness","linkedin"],"summary":"Get a tracking window","description":"Returns one tracking window with the latest verified numbers we read from the platform. Once the window\nhas completed, `finalReadAt` and `completionReason` say how it closed.\n","parameters":[{"name":"windowId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The tracking window","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackingWindowResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/AnalyticsAddonRequired"},"403":{"description":"API key scope violation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Tracking window not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"}}},"delete":{"x-resource-group":"analytics","operationId":"cancelTrackingWindow","tags":["Analytics"],"x-platforms":["instagram","facebook","tiktok","youtube","twitter","threads","pinterest","reddit","bluesky","googlebusiness","linkedin"],"summary":"Cancel a tracking window","description":"Stops tracking and returns the window with its final status. A window that already completed keeps its\n`completed` status and its final read. A cancelled window gets no final read and fires no\n`post.tracking_completed` webhook.\n","parameters":[{"name":"windowId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The window after cancellation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackingWindowResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/AnalyticsAddonRequired"},"403":{"description":"API key scope violation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Tracking window not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/analytics/samples":{"get":{"x-resource-group":"analytics","operationId":"getPostSamples","tags":["Analytics"],"x-platforms":["instagram","facebook","tiktok","youtube","twitter","threads","pinterest","reddit","bluesky","googlebusiness","linkedin"],"summary":"Get post samples","description":"Returns the raw readings behind a post's numbers, oldest first.\n\nEach sample is one analytics sync: the views and engagement as the platform reported them at `syncedAt`. Zernio only stores what it fetched from the platform, so nothing here was self-reported.\n\n### Null values\n\n- `shares` and `saves` are null on platforms that do not return that counter, which is different from a real zero.\n- `watchSeconds` and `completionRate` are null when the platform gives no watch signal.\n","parameters":[{"name":"postId","in":"query","required":true,"schema":{"type":"string"},"description":"The post to read samples for. Accepts an external post id, a platform post id or a Zernio post id."},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date-time"},"description":"Earliest sample to return (ISO 8601)."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date-time"},"description":"Latest sample to return (ISO 8601)."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":2000,"default":500},"description":"Maximum number of samples."}],"responses":{"200":{"description":"Samples for the post","content":{"application/json":{"schema":{"type":"object","required":["postId","samples"],"properties":{"postId":{"type":"string","description":"The postId that was requested"},"samples":{"type":"array","items":{"$ref":"#/components/schemas/PostSample"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/AnalyticsAddonRequired"},"403":{"description":"API key scope violation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Post not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"}}}},"/v1/posts/{postId}/authenticity":{"get":{"x-resource-group":"analytics","operationId":"getPostAuthenticity","tags":["Analytics"],"x-platforms":["instagram","facebook","tiktok","youtube","twitter","threads","pinterest","reddit","bluesky","googlebusiness","linkedin"],"summary":"Get a post's authenticity score","description":"Returns Zernio's authenticity score for a post: an integer from 0 to 100 where higher means the view pattern looks more like organic viewing.\n\nThe score is ours. It is computed only from the verified samples we fetched from the platform, never from anything the creator or caller reported.\n\n- `reasons` lists each factor that lowered it with its weight in points.\n- `confidence` (0 to 1) says how much data the score rests on.\n\nA stored score newer than 30 minutes is returned as is, otherwise it is recomputed. The `post.authenticity_changed` webhook fires when a score crosses 40.\n","parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"},"description":"An external post id, a platform post id or a Zernio post id."}],"responses":{"200":{"description":"The post's authenticity score","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostAuthenticity"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/AnalyticsAddonRequired"},"403":{"description":"API key scope violation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Post not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/analytics/authenticity":{"get":{"x-resource-group":"analytics","operationId":"listPostAuthenticity","tags":["Analytics"],"x-platforms":["instagram","facebook","tiktok","youtube","twitter","threads","pinterest","reddit","bluesky","googlebusiness","linkedin"],"summary":"List authenticity scores","description":"Lists the stored authenticity scores for one connected account, newest first. Requires the Analytics add-on.\n\nScores are 0 to 100 and come from Zernio's own model over verified platform samples.\n\n### Filters\n\n- `minScore` and `maxScore`: find posts that look inflated.\n- `from` and `to`: bound when the score was computed.\n","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The connected account to list scores for."},{"name":"minScore","in":"query","schema":{"type":"integer","minimum":0,"maximum":100},"description":"Only scores at or above this value."},{"name":"maxScore","in":"query","schema":{"type":"integer","minimum":0,"maximum":100},"description":"Only scores at or below this value."},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only scores computed at or after this time (ISO 8601)."},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only scores computed at or before this time (ISO 8601)."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Page size."},{"name":"skip","in":"query","schema":{"type":"integer","minimum":0,"default":0},"description":"Number of scores to skip."}],"responses":{"200":{"description":"Authenticity scores","content":{"application/json":{"schema":{"type":"object","required":["scores"],"properties":{"scores":{"type":"array","items":{"$ref":"#/components/schemas/PostAuthenticity"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/AnalyticsAddonRequired"},"403":{"description":"API key scope violation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/analytics/googlebusiness/performance":{"get":{"x-resource-group":"analytics","operationId":"getGoogleBusinessPerformance","tags":["Analytics"],"summary":"Get Google Business Profile performance metrics","description":"Returns daily performance metrics for a Google Business Profile location.\nMetrics include impressions (Maps/Search, desktop/mobile), website clicks,\ncall clicks, direction requests, conversations, bookings, and food orders.\nData may be delayed 2-3 days. Max 18 months of historical data.\n","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The Zernio SocialAccount ID for the Google Business Profile account."},{"name":"metrics","in":"query","schema":{"type":"string"},"description":"Comma-separated metric names. Defaults to all available metrics.\nValid values: BUSINESS_IMPRESSIONS_DESKTOP_MAPS, BUSINESS_IMPRESSIONS_DESKTOP_SEARCH,\nBUSINESS_IMPRESSIONS_MOBILE_MAPS, BUSINESS_IMPRESSIONS_MOBILE_SEARCH,\nBUSINESS_CONVERSATIONS, BUSINESS_DIRECTION_REQUESTS, CALL_CLICKS, WEBSITE_CLICKS,\nBUSINESS_BOOKINGS, BUSINESS_FOOD_ORDERS, BUSINESS_FOOD_MENU_CLICKS\n"},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Start date (YYYY-MM-DD). Defaults to 30 days ago. Max 18 months back."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"End date (YYYY-MM-DD). Defaults to today."},{"name":"startDate","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of fromDate, kept for existing callers"},{"name":"endDate","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of toDate, kept for existing callers"}],"responses":{"200":{"description":"Performance metrics with daily time series","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"accountId":{"type":"string"},"platform":{"type":"string","example":"googlebusiness"},"dateRange":{"type":"object","properties":{"startDate":{"type":"string","format":"date","example":"2026-03-01"},"endDate":{"type":"string","format":"date","example":"2026-03-31"}}},"metrics":{"type":"object","description":"Each key is a metric name containing total and daily values.","additionalProperties":{"type":"object","properties":{"total":{"type":"integer","description":"Sum of all daily values in the range"},"values":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"value":{"type":"integer"}}}}}}},"dataDelay":{"type":"string","example":"Data may be delayed 2-3 days"}}},"examples":{"performance_data":{"summary":"Performance metrics for a location","value":{"success":true,"accountId":"69300690f43160a0bc999e07","platform":"googlebusiness","dateRange":{"startDate":"2026-03-01","endDate":"2026-03-31"},"metrics":{"WEBSITE_CLICKS":{"total":42,"values":[{"date":"2026-03-01","value":3},{"date":"2026-03-02","value":1}]},"CALL_CLICKS":{"total":7,"values":[{"date":"2026-03-01","value":1}]},"BUSINESS_IMPRESSIONS_MOBILE_SEARCH":{"total":156,"values":[{"date":"2026-03-01","value":8}]}},"dataDelay":"Data may be delayed 2-3 days"}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid metrics: INVALID_METRIC"},"validMetrics":{"type":"array","items":{"type":"string"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Analytics add-on required"},"code":{"type":"string","example":"analytics_addon_required"}}}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Access denied to this account"}}}}}},"502":{"$ref":"#/components/responses/UpstreamFailure"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/v1/analytics/googlebusiness/search-keywords":{"get":{"x-resource-group":"analytics","operationId":"getGoogleBusinessSearchKeywords","tags":["Analytics"],"summary":"Get Google Business Profile search keywords","description":"Returns search keywords that triggered impressions for a Google Business Profile location.\n\n- Data is aggregated monthly.\n- Keywords Google reports only as below a threshold have `impressions` 0 and `impressionsThreshold` set to that threshold.\n- Max 18 months of historical data.\n\n### Paging\n\nReturns up to 100 keywords per page. When `nextPageToken` is not null, pass it as `pageToken` with the same `startMonth` and `endMonth` to get the next page.\n","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The Zernio SocialAccount ID for the Google Business Profile account."},{"name":"startMonth","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"description":"Start month (YYYY-MM). Defaults to 3 months ago."},{"name":"endMonth","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"description":"End month (YYYY-MM). Defaults to current month."},{"name":"pageToken","in":"query","schema":{"type":"string"},"description":"The nextPageToken from the previous page. Valid only with the same startMonth and endMonth as the request that returned it."}],"responses":{"200":{"description":"Search keywords with impression counts","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"accountId":{"type":"string"},"platform":{"type":"string","example":"googlebusiness"},"monthRange":{"type":"object","properties":{"startMonth":{"type":"string","example":"2026-01"},"endMonth":{"type":"string","example":"2026-03"}}},"keywords":{"type":"array","items":{"type":"object","properties":{"keyword":{"type":"string","example":"restaurant near me"},"impressions":{"type":"integer","example":245,"description":"Impressions for the range. 0 when Google reports only a threshold."},"impressionsThreshold":{"type":["integer","null"],"example":null,"description":"Set when Google reports only that impressions were below this value. null when impressions is exact."}}}},"nextPageToken":{"type":["string","null"],"description":"Pass as pageToken to fetch the next page. null on the last page."},"note":{"type":"string","example":"Keywords Google reports only as below a threshold have impressions 0 and impressionsThreshold set"}}},"examples":{"keywords_data":{"summary":"Search keywords for a location","value":{"success":true,"accountId":"69300690f43160a0bc999e07","platform":"googlebusiness","monthRange":{"startMonth":"2026-01","endMonth":"2026-03"},"keywords":[{"keyword":"restaurant near me","impressions":245,"impressionsThreshold":null},{"keyword":"best tapas barcelona","impressions":89,"impressionsThreshold":null},{"keyword":"zernio","impressions":34,"impressionsThreshold":null},{"keyword":"tapas delivery","impressions":0,"impressionsThreshold":15}],"nextPageToken":null,"note":"Keywords Google reports only as below a threshold have impressions 0 and impressionsThreshold set"}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid startMonth format. Use YYYY-MM."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Analytics add-on required"},"code":{"type":"string","example":"analytics_addon_required"}}}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Access denied to this account"}}}}}},"502":{"$ref":"#/components/responses/UpstreamFailure"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/v1/analytics/inbox/volume":{"get":{"x-resource-group":"analytics","operationId":"getInboxVolume","tags":["Inbox Analytics"],"summary":"Get inbox messaging volume","description":"Daily inbox messaging volume + breakdowns. Folds the raw messaging\nevents into three projections so the client can render the volume\nchart, KPI strip, and per-platform stacked bar from a single call.\nMax date range is 365 days.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"fromDate","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Inclusive lower bound (YYYY-MM-DD). Required."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"Inclusive upper bound (YYYY-MM-DD). Defaults to today."},{"name":"profileId","in":"query","schema":{"type":"string"}},{"name":"platform","in":"query","schema":{"type":"string"},"description":"Filter by single platform (facebook, instagram, twitter, etc.)."},{"name":"accountId","in":"query","schema":{"type":"string"}},{"name":"source","in":"query","schema":{"type":"string"},"description":"Filter by metadata.source lineage (human, workflow, sequence, broadcast, comment_automation, api, contact, platform)."}],"responses":{"200":{"description":"Volume breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"from":{"type":"string","format":"date"},"to":{"type":["string","null"],"format":"date"},"summary":{"type":"object","properties":{"received":{"type":"integer"},"sent":{"type":"integer"},"read":{"type":"integer"},"failed":{"type":"integer"},"uniqueConversations":{"type":"integer"}}},"timeseries":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"sent":{"type":"integer"},"received":{"type":"integer"},"read":{"type":"integer"},"failed":{"type":"integer"}}}},"byPlatform":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"sent":{"type":"integer"},"received":{"type":"integer"},"read":{"type":"integer"},"failed":{"type":"integer"}}}}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/analytics/inbox/heatmap":{"get":{"x-resource-group":"analytics","operationId":"getInboxHeatmap","tags":["Inbox Analytics"],"summary":"Get day × hour heatmap","description":"Day-of-week × hour-of-day breakdown of inbox messages. Buckets are\nsparse: only cells with at least one event are returned; clients\nzero-fill the rest to render the full 7×24 grid. The `dow` field\nfollows ClickHouse's `toDayOfWeek` convention (1 = Monday … 7 =\nSunday). Max date range is 365 days.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"fromDate","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"}},{"name":"profileId","in":"query","schema":{"type":"string"}},{"name":"platform","in":"query","schema":{"type":"string"}},{"name":"accountId","in":"query","schema":{"type":"string"}},{"name":"source","in":"query","schema":{"type":"string"}},{"name":"action","in":"query","schema":{"type":"string","enum":["message.received","message.sent","message.read","all"]},"description":"Narrow to a single event type. \"all\" or omitted means no filter."}],"responses":{"200":{"description":"Heatmap buckets","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"from":{"type":"string","format":"date"},"to":{"type":["string","null"],"format":"date"},"buckets":{"type":"array","items":{"type":"object","properties":{"dow":{"type":"integer","minimum":1,"maximum":7,"description":"1 = Monday, 7 = Sunday"},"hour":{"type":"integer","minimum":0,"maximum":23},"received":{"type":"integer"},"sent":{"type":"integer"},"read":{"type":"integer"}}}}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/analytics/inbox/source-breakdown":{"get":{"x-resource-group":"analytics","operationId":"getInboxSourceBreakdown","tags":["Inbox Analytics"],"summary":"Get inbox source breakdown","description":"Breakdown of inbox messages by their lineage source (the\n`metadata.source` field set at ingest time: human / workflow /\nsequence / broadcast / comment_automation / api / contact /\nplatform). Each source row also carries a per-platform sub-split.\nMax date range is 365 days.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"fromDate","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"}},{"name":"profileId","in":"query","schema":{"type":"string"}},{"name":"platform","in":"query","schema":{"type":"string"}},{"name":"accountId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Source breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"from":{"type":"string","format":"date"},"to":{"type":["string","null"],"format":"date"},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"received":{"type":"integer"},"sent":{"type":"integer"},"read":{"type":"integer"},"byPlatform":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"received":{"type":"integer"},"sent":{"type":"integer"},"read":{"type":"integer"}}}}}}}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/analytics/inbox/response-time":{"get":{"x-resource-group":"analytics","operationId":"getInboxResponseTime","tags":["Inbox Analytics"],"summary":"Get inbox response-time stats","description":"Time-to-first-response stats. Pairs each received message with the\nnext sent message in the same conversation and reports the delta\nas both summary statistics and a fixed-bucket histogram suited\nfor the analytics page's TTR chart.\n\n`sampleSize` reflects only conversations that received AND got a\nreply in the window. Received-but-never-answered conversations\nare excluded. Compare against /v1/analytics/inbox/volume's\n`summary.received` to compute reply rate.\n\nMax date range is 365 days.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"fromDate","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"}},{"name":"profileId","in":"query","schema":{"type":"string"}},{"name":"platform","in":"query","schema":{"type":"string"}},{"name":"accountId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Response-time summary + histogram","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"from":{"type":"string","format":"date"},"to":{"type":["string","null"],"format":"date"},"summary":{"type":"object","properties":{"sampleSize":{"type":"integer"},"medianSeconds":{"type":"integer"},"p90Seconds":{"type":"integer"},"p99Seconds":{"type":"integer"},"meanSeconds":{"type":"integer"},"fastestSeconds":{"type":"integer"},"slowestSeconds":{"type":"integer"}}},"histogram":{"type":"array","items":{"type":"object","properties":{"bucket":{"type":"string","description":"Human label (0-1m, 1-5m, 5-15m, 15-60m, 1-4h, 4-24h, 1d+)"},"lowerSeconds":{"type":"integer"},"upperSeconds":{"type":["integer","null"],"description":"null on the open-ended last bucket"},"count":{"type":"integer"}}}}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/analytics/inbox/top-accounts":{"get":{"x-resource-group":"analytics","operationId":"getInboxTopAccounts","tags":["Inbox Analytics"],"summary":"Get top accounts by inbox volume","description":"Leaderboard of accounts by inbox message volume. Max date range is 365 days.\n\n- Each row is decorated with display labels from the live SocialAccount record (so the UI shows username + displayName, not only an ID).\n- Accounts that no longer map to a SocialAccount surface as \"(disconnected)\" so the row stays visible.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"fromDate","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"}},{"name":"profileId","in":"query","schema":{"type":"string"}},{"name":"platform","in":"query","schema":{"type":"string"}},{"name":"source","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"description":"Cap on returned rows. Lower than the posting listing's 100 because each row triggers a social account lookup."}],"responses":{"200":{"description":"Top accounts leaderboard","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"from":{"type":"string","format":"date"},"to":{"type":["string","null"],"format":"date"},"accounts":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string"},"displayName":{"type":"string","description":"(disconnected) when the SocialAccount no longer exists"},"username":{"type":"string"},"received":{"type":"integer"},"sent":{"type":"integer"},"total":{"type":"integer"},"conversations":{"type":"integer"},"medianResponseSeconds":{"type":"integer"},"repliedCount":{"type":"integer","description":"Distinguishes 'instant replies' from 'no replies at all' so a zero medianResponseSeconds with repliedCount=0 renders as an em dash instead of '0s'"}}}}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/analytics/inbox/conversations":{"get":{"x-resource-group":"messages","operationId":"listInboxConversationAnalytics","tags":["Inbox Analytics"],"summary":"List conversation analytics","description":"Per-conversation listing with per-row totals + first/last message\ntimestamps. The inbox analog of GET /v1/analytics (posts listing):\nsame filter shape, same pagination, same sort/order semantics.\nUse as the entry point for the per-conversation analytics drawer\nat /v1/analytics/inbox/conversations/{conversationId}.\n\nRows are enriched with the conversation's participant info\n(`participantName`, `participantUsername`, `participantPicture`)\nand last-message preview by joining the Conversation document\nscoped to the caller's team. Max date range is 365 days.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"fromDate","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"}},{"name":"profileId","in":"query","schema":{"type":"string"}},{"name":"platform","in":"query","schema":{"type":"string"}},{"name":"accountId","in":"query","schema":{"type":"string"}},{"name":"source","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["lastMessageAt","firstMessageAt","totalMessages","received","sent","read","failed"],"default":"lastMessageAt"}},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}}],"responses":{"200":{"description":"Paginated conversation analytics list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"from":{"type":"string","format":"date"},"to":{"type":["string","null"],"format":"date"},"items":{"type":"array","items":{"type":"object","properties":{"conversationId":{"type":"string","description":"The platformConversationId. A thread whose events were logged under both its ids comes back as one row."},"mongoId":{"type":["string","null"],"description":"The Zernio conversation id, when a matching conversation exists"},"accountId":{"type":"string"},"platform":{"type":"string"},"participantName":{"type":["string","null"]},"participantUsername":{"type":["string","null"]},"participantPicture":{"type":["string","null"]},"lastMessage":{"type":["string","null"],"description":"Cached preview from the Conversation doc"},"totalMessages":{"type":"integer"},"received":{"type":"integer"},"sent":{"type":"integer"},"read":{"type":"integer"},"failed":{"type":"integer"},"firstMessageAt":{"type":"string","format":"date-time"},"lastMessageAt":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/analytics/inbox/conversations/{conversationId}":{"get":{"x-resource-group":"messages","operationId":"getInboxConversationAnalytics","tags":["Inbox Analytics"],"summary":"Get conversation analytics","description":"Per-conversation inbox analytics. The inbox analog of\n/v1/analytics/post-timeline: one conversation, daily totals,\nsource mix.\n\nThe {conversationId} path param accepts EITHER the Zernio\nconversation id OR its `platformConversationId` (the same\nidentity used by metadata.conversationId at ingest time).\nOwnership is verified against the caller's team before the\nTinybird query fires.\n\nMax date range is 365 days.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"Zernio conversation id or platformConversationId."},{"name":"fromDate","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Per-conversation analytics","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"conversationId":{"type":"string","description":"The platformConversationId"},"mongoId":{"type":"string"},"platform":{"type":["string","null"]},"from":{"type":"string","format":"date"},"to":{"type":["string","null"],"format":"date"},"summary":{"type":"object","properties":{"received":{"type":"integer"},"sent":{"type":"integer"},"read":{"type":"integer"},"failed":{"type":"integer"},"totalMessages":{"type":"integer"},"firstMessageAt":{"type":["string","null"],"format":"date-time"},"lastMessageAt":{"type":["string","null"],"format":"date-time"}}},"timeseries":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"sent":{"type":"integer"},"received":{"type":"integer"},"read":{"type":"integer"},"failed":{"type":"integer"}}}},"bySource":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","description":"(unspecified) for legacy rows with no metadata.source"},"count":{"type":"integer"}}}}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Conversation not found or not owned by the caller's team","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Conversation not found."},"code":{"type":"string","example":"conversation_not_found"}}}}}},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/account-groups":{"get":{"x-resource-group":"accounts","operationId":"listAccountGroups","tags":["Account Groups"],"summary":"List groups","description":"Returns all account groups visible to the authenticated user. Groups can\ncontain accounts from multiple profiles. For API keys scoped to specific\nprofiles, only groups whose accounts all live in allowed profiles are\nreturned.\n","responses":{"200":{"description":"Groups","content":{"application/json":{"schema":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"accountIds":{"type":"array","items":{"type":"string"}},"createdBy":{"type":"string"},"profileId":{"type":"string","description":"Legacy field. Present only on groups created before\ncross-profile groups were supported. New groups omit it.\n"}}}}}},"examples":{"example":{"value":{"groups":[{"_id":"6507a1b2c3d4e5f6a7b8c9d0","name":"Marketing Accounts","accountIds":["64e1f0a9e2b5af0012ab34cd","64e1f0a9e2b5af0012ab34ce"]},{"_id":"6507a1b2c3d4e5f6a7b8c9d1","name":"Personal Brand","accountIds":["64e1f0a9e2b5af0012ab34cf"]}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"x-resource-group":"accounts","operationId":"createAccountGroup","tags":["Account Groups"],"summary":"Create group","description":"Creates a new account group with a name and a list of account IDs.\nAccounts can belong to different profiles; the caller must have access to\nevery account's profile. Group names must be unique per user.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","accountIds"],"properties":{"name":{"type":"string"},"accountIds":{"type":"array","items":{"type":"string"}},"profileId":{"type":"string","description":"Deprecated. Accepted for backward compatibility but ignored.\nGroups are no longer scoped to a single profile.\n","deprecated":true}}},"example":{"name":"Marketing Accounts","accountIds":["64e1f0a9e2b5af0012ab34cd","64e1f0a9e2b5af0012ab34ce"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"group":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"accountIds":{"type":"array","items":{"type":"string"}}}}}},"example":{"message":"Account group created successfully","group":{"_id":"6507a1b2c3d4e5f6a7b8c9d0","name":"Marketing Accounts","accountIds":["64e1f0a9e2b5af0012ab34cd","64e1f0a9e2b5af0012ab34ce"]}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"description":"Group name already exists"}}}},"/v1/account-groups/{groupId}":{"put":{"x-resource-group":"accounts","operationId":"updateAccountGroup","tags":["Account Groups"],"summary":"Update group","description":"Updates the name or account list of an existing group. You can rename the group, change its accounts, or both.","parameters":[{"name":"groupId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"accountIds":{"type":"array","items":{"type":"string"}}}},"example":{"name":"Updated Marketing Accounts","accountIds":["64e1f0a9e2b5af0012ab34cd","64e1f0a9e2b5af0012ab34ce","64e1f0a9e2b5af0012ab34cf"]}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"group":{"type":"object"}}},"example":{"message":"Account group updated successfully","group":{"_id":"6507a1b2c3d4e5f6a7b8c9d0","name":"Updated Marketing Accounts","accountIds":["64e1f0a9e2b5af0012ab34cd","64e1f0a9e2b5af0012ab34ce","64e1f0a9e2b5af0012ab34cf"]}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Group name already exists"}}},"delete":{"x-resource-group":"accounts","operationId":"deleteAccountGroup","tags":["Account Groups"],"summary":"Delete group","description":"Permanently deletes an account group. The accounts themselves are not affected.","parameters":[{"name":"groupId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}},"example":{"message":"Account group deleted successfully"}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/media/presign":{"post":{"x-resource-group":"publishing","operationId":"getMediaPresignedUrl","tags":["Media"],"summary":"Get upload URL","description":"Get a presigned URL to upload files directly to cloud storage (up to 5GB). Returns an uploadUrl and publicUrl. PUT your file to the uploadUrl, then use the publicUrl in your posts.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["filename","contentType"],"properties":{"filename":{"type":"string","description":"Name of the file to upload","example":"my-video.mp4"},"contentType":{"$ref":"#/components/schemas/MediaContentType"},"size":{"type":"integer","description":"Optional file size in bytes for pre-validation (max 5GB)","example":15234567}}}}}},"responses":{"200":{"description":"Presigned URL generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uploadUrl":{"type":"string","format":"uri","description":"Presigned URL to PUT your file to (expires in 1 hour)"},"publicUrl":{"type":"string","format":"uri","description":"Public URL where the file will be accessible after upload"},"key":{"type":"string","description":"Storage key/path of the file"},"expiresIn":{"type":"integer","description":"Seconds until the presigned uploadUrl expires (always 3600)"}}},"example":{"uploadUrl":"<presigned-upload-url>","publicUrl":"https://media.zernio.com/temp/1234567890_abc123_my-video.mp4","key":"temp/1234567890_abc123_my-video.mp4","expiresIn":3600}}}},"400":{"description":"Invalid request (missing filename, unsupported contentType, or size out of range)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/reddit/search":{"get":{"x-resource-group":"engagement","operationId":"searchReddit","tags":["Reddit Search"],"summary":"Search posts","description":"Temporarily unavailable: Reddit has blocked third-party apps from its API, so this endpoint returns 503 `PLATFORM_DISABLED` until Reddit restores access. Reddit Ads is not affected.\n\nSearch Reddit posts using a connected account. Optionally scope to a specific subreddit.\n","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"subreddit","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"restrict_sr","in":"query","schema":{"type":"string","enum":["0","1"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["relevance","hot","top","new","comments"],"default":"new"}},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":100}},{"name":"after","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RedditPost"}},"after":{"type":["string","null"]},"before":{"type":["string","null"]}}},"example":{"items":[{"id":"1abc234","fullname":"t3_1abc234","title":"How to grow on social media in 2025","selftext":"Here are my tips...","author":"marketingpro","subreddit":"socialmedia","url":"https://www.reddit.com/r/socialmedia/comments/1abc234/","permalink":"https://www.reddit.com/r/socialmedia/comments/1abc234/how_to_grow/","score":156,"numComments":42,"createdUtc":1730000000,"over18":false,"stickied":false,"flairText":null,"isGallery":false}],"after":"t3_1abc234","before":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"x-summary":"No active Reddit account with this ID is available to the key: reconnecting issues a new ID, so read the accounts list.","description":"No active Reddit account with this ID is available to the API key.\nIt may have been disconnected or deleted, or it belongs to a profile\nthe key cannot access. Re-connecting an account issues a NEW account\nID, so an ID stored from before a reconnect will not resolve.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"Organic Reddit is temporarily unavailable while Reddit blocks third-party API access (`PLATFORM_DISABLED`)."}}}},"/v1/reddit/feed":{"get":{"x-resource-group":"engagement","operationId":"getRedditFeed","tags":["Reddit Search"],"summary":"Get subreddit feed","description":"Temporarily unavailable: Reddit has blocked third-party apps from its API, so this endpoint returns 503 `PLATFORM_DISABLED` until Reddit restores access. Reddit Ads is not affected.\n\nFetch posts from a subreddit feed. Supports sorting, time filtering, and cursor-based pagination.\n","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"subreddit","in":"query","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["hot","new","top","rising"],"default":"hot"}},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":100}},{"name":"after","in":"query","schema":{"type":"string"}},{"name":"t","in":"query","schema":{"type":"string","enum":["hour","day","week","month","year","all"]}}],"responses":{"200":{"description":"Feed items","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RedditPost"}},"after":{"type":["string","null"]},"before":{"type":["string","null"]}}},"example":{"items":[{"id":"1xyz789","fullname":"t3_1xyz789","title":"Top marketing trends this week","author":"trendwatcher","subreddit":"marketing","url":"https://www.reddit.com/r/marketing/comments/1xyz789/","permalink":"https://www.reddit.com/r/marketing/comments/1xyz789/top_marketing_trends/","score":892,"numComments":134,"createdUtc":1730100000,"over18":false,"stickied":false,"flairText":null,"isGallery":false},{"id":"1def456","fullname":"t3_1def456","title":"Check out my grow setup","author":"growthexpert","subreddit":"gardening","url":"https://www.reddit.com/gallery/1def456","permalink":"https://www.reddit.com/r/gardening/comments/1def456/check_out_my_grow_setup/","score":567,"numComments":89,"createdUtc":1730050000,"over18":false,"stickied":false,"flairText":null,"isGallery":true,"galleryImages":["https://i.redd.it/abc123.jpg","https://i.redd.it/def456.jpg"]}],"after":"t3_1def456","before":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"x-summary":"No active Reddit account with this ID is available to the key: reconnecting issues a new ID, so read the accounts list.","description":"No active Reddit account with this ID is available to the API key.\nIt may have been disconnected or deleted, or it belongs to a profile\nthe key cannot access. Re-connecting an account issues a NEW account\nID, so an ID stored from before a reconnect will not resolve.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"Organic Reddit is temporarily unavailable while Reddit blocks third-party API access (`PLATFORM_DISABLED`)."}}}},"/v1/reddit/comments/{postId}":{"get":{"x-resource-group":"engagement","operationId":"getRedditPostComments","tags":["Reddit Search"],"summary":"Get the comments of a Reddit post","description":"Temporarily unavailable: Reddit has blocked third-party apps from its API, so this endpoint returns 503 `PLATFORM_DISABLED` until Reddit restores access. Reddit Ads is not affected.\n\nReads the comments of any Reddit post the connected account can see, for example one found through `/v1/reddit/feed` or `/v1/reddit/search`, straight from Reddit on every call.\n\n### Thread shape\n\n- The tree comes flattened in thread order (a reply follows its parent).\n- Rebuild it from `parentId`, which is `t3_…` for a reply to the post and `t1_…` for a reply to a comment.\n- Deleted and removed comments are passed through as Reddit sends them (`[deleted]` / `[removed]`).\n- Where Reddit truncates a thread, the ids it left out are listed in `more`. `commentId` fetches one such comment with its replies.\n\n### Errors\n\n- 404 `platform_api_error`: Reddit no longer serves the post.\n- 403 `platform_api_error`: the subreddit is private.\n\nFor comments on posts published through Zernio, `/v1/inbox/comments/{postId}` adds caching, moderation and replies.\n","parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"},"description":"Reddit post id, with or without the `t3_` prefix (as `id` or `fullname` on RedditPost)."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"An active Reddit account the request is made as."},{"name":"sort","in":"query","schema":{"type":"string","enum":["new","top","best","controversial","old","qa"],"default":"new"}},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":100},"description":"Maximum number of top-level comments."},{"name":"commentId","in":"query","schema":{"type":"string"},"description":"Return only this comment and its replies, with or without the `t1_` prefix; pass an id from `more` to expand it."}],"responses":{"200":{"description":"The post and its comments","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"oneOf":[{"$ref":"#/components/schemas/RedditPost"},{"type":"null"}],"description":"The post header; null when Reddit omits it (deleted post)."},"items":{"type":"array","items":{"$ref":"#/components/schemas/RedditComment"}},"more":{"type":"array","items":{"type":"string"},"description":"Ids of comments Reddit left out of this page, at any depth."}}},"example":{"post":{"id":"1abc23","fullname":"t3_1abc23","title":"We moved our scheduling to an API","author":"founder_jo","subreddit":"saas","url":"https://www.reddit.com/r/saas/comments/1abc23/we_moved_our_scheduling_to_an_api/","permalink":"https://www.reddit.com/r/saas/comments/1abc23/we_moved_our_scheduling_to_an_api/","selftext":"Long story short...","score":88,"numComments":41,"createdUtc":1791190000,"over18":false,"stickied":false,"flairText":null,"isGallery":false},"items":[{"id":"k9x2f1","fullname":"t1_k9x2f1","parentId":"t3_1abc23","author":"someone","body":"We moved to Zernio last month...","permalink":"https://www.reddit.com/r/saas/comments/1abc23/we_moved_our_scheduling_to_an_api/k9x2f1/","createdUtc":1791200000,"score":12,"numReplies":1,"depth":0,"isSubmitter":false,"edited":false,"stickied":false,"distinguished":null},{"id":"k9x3aa","fullname":"t1_k9x3aa","parentId":"t1_k9x2f1","author":"founder_jo","body":"Same here.","permalink":"https://www.reddit.com/r/saas/comments/1abc23/we_moved_our_scheduling_to_an_api/k9x3aa/","createdUtc":1791200600,"score":3,"numReplies":0,"depth":1,"isSubmitter":true,"edited":false,"stickied":false,"distinguished":null}],"more":["k9x9zz","k9xa01"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Reddit refused the thread, typically a private or quarantined subreddit (`platform_api_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"x-summary":"No active Reddit account with this ID is available, or Reddit no longer serves the post: check the ID and the post.","description":"Either no active Reddit account with this ID is available to the API key\n(`account_not_found`), or Reddit no longer serves the post, for example because it was\ndeleted (`platform_api_error`).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"Organic Reddit is temporarily unavailable while Reddit blocks third-party API access (`PLATFORM_DISABLED`)."}}}},"/v1/billing":{"get":{"x-resource-group":"billing","operationId":"getBilling","tags":["Usage"],"summary":"Account billing snapshot (plan, cycle, balance, caps, status)","description":"The billing \"wallet/statement\" view: current plan, billing cycle,\naccrued balance + remaining credits this period, spend caps, and\npayment / access status. This is the billing half of the legacy\n`/v1/usage-stats` snapshot. The per-product consumption half is metering\nand lives on `GET /v1/usage`.\n\nAccounts on usage-based billing get a populated `balance`; legacy Stripe\naccounts get `balance: null` plus a deprecated `legacy.limits` block and,\nwhen payment-blocked, `status.openInvoiceUrl` / `status.declineReason`.\n","responses":{"200":{"description":"Billing snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingSnapshot"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/billing/x-pricing":{"get":{"x-resource-group":"billing","operationId":"getXApiPricing","tags":["Usage"],"summary":"Get X API pricing table","description":"Returns Zernio's canonical X API pricing table. Each X action has its\nown billing product and its own rate, and Zernio passes X API costs through\nat exact rates with zero markup.\n\nThe response is identical for every authenticated user (pricing is universal),\nso it is safe to cache on the client for the duration of a billing period.\n\nTo compute your own per-operation spend, pair this endpoint with\n`GET /v1/usage-stats`, which returns `usage.xApiCallsByOperation`\nkeyed by the same `operation` field you get here.\n","responses":{"200":{"description":"X pricing table","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XApiPricing"},"example":{"currency":"USD","markup":"0%","source":"https://developer.x.com/#pricing","lastVerified":"2026-03-26","tiers":[{"tier":"x_api_005","pricePerCallUsd":0.005,"operationCount":13},{"tier":"x_api_010","pricePerCallUsd":0.01,"operationCount":10},{"tier":"x_api_015","pricePerCallUsd":0.015,"operationCount":3},{"tier":"x_api_200","pricePerCallUsd":0.2,"operationCount":1}],"operations":[{"operation":"posts_read","eventType":"x_posts_read","displayName":"X API: Posts Read","pricePerCallUsd":0.005,"pricePerCallCents":0.5,"tier":"x_api_005","triggeredBy":[{"method":"getPostAnalytics","metering":"analytics_optin"},{"method":"getBatchPostAnalytics","metering":"analytics_optin"},{"method":"getAccountPosts","metering":"analytics_optin"}]},{"operation":"content_create","eventType":"x_content_create","displayName":"X API: Content Create","pricePerCallUsd":0.015,"pricePerCallCents":1.5,"tier":"x_api_015","triggeredBy":[{"method":"publishPost","metering":"always"}]},{"operation":"content_create_with_url","eventType":"x_content_create_with_url","displayName":"X API: Content Create (with URL)","pricePerCallUsd":0.2,"pricePerCallCents":20,"tier":"x_api_200","triggeredBy":[{"method":"publishPost","metering":"always"}]},{"operation":"article_draft","eventType":"x_article_draft","displayName":"X API: Article Draft","pricePerCallUsd":0.01,"pricePerCallCents":1,"tier":"x_api_010","triggeredBy":[{"method":"createArticleDraft","metering":"always"}]},{"operation":"article_publish","eventType":"x_article_publish","displayName":"X API: Article Publish","pricePerCallUsd":0.01,"pricePerCallCents":1,"tier":"x_api_010","triggeredBy":[{"method":"publishArticle","metering":"always"}]}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/usage":{"get":{"x-resource-group":"billing","operationId":"getUsage","tags":["Usage"],"summary":"Usage snapshot (default) or billed-spend metering (with params)","description":"Dual-mode endpoint, selected by query params, and fully backward compatible.\n\n### Without metering params (the default)\n\nReturns the plan / quota / usage snapshot: plan name, billing period, limits, usage counts, access state. Identical to `GET /v1/usage-stats`. Existing integrations keep working unchanged.\n\n### With `range`, `granularity`, `from`, or `to`\n\nReturns usage METERING: billed spend (USD) by product family over the window, at `day` / `month` / `total` granularity. Product families: `accounts`, `numbers`, `imessage`, `calls`, `sms`, `messages`, `verify`, `dlc`, `xApi`, `ads`, `credits`, `other`.\n\nData comes from the usage-based invoice breakdown (the CHARGE view, which always reconciles with what gets billed). Also served at `GET /v1/usage/daily`.\n\nUsage-based accounts only: legacy Stripe accounts get `{ \"supported\": false, \"days\": [] }`.\n\n### Attribution (metering mode)\n\n`groupBy=profile|account` adds an `attribution` breakdown of the window's spend per profile or account. It is assembled from your own records and pro-rated against the invoice so `sum(groups) + unattributed` equals `totals` exactly.\n\n`profileId` / `accountId` instead project the whole payload (`days`, `totals`, `lineItems`) onto that one group:\n\n- `peaks`, `callUsage` and `tax` are then `null` (team-level facts).\n- Projected `days` spread the group's period share over each day (usage is attributed per period, not per day).\n- `profileId` / `accountId` on their own do not select metering mode: pair them with `range`.\n\nProfile-scoped API keys and members only see their profiles' groups (`attribution.restricted: true`, with `totals` summing the visible groups). Credits, 10DLC fees and Verify are always unattributed.\n\n### Related endpoints\n\n- Per-domain consumption *volumes*: `GET /v1/usage/calls` and `GET /v1/usage/sms`.\n- The billing statement (balance, credits, caps, payment status): `GET /v1/billing`.\n","parameters":[{"name":"reconcile","in":"query","required":false,"schema":{"type":"boolean"},"description":"Snapshot mode only. For Stripe subscription users, `true` forces a\nsubscription reconciliation pass even when cached plan data looks\ncomplete.\n"},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["cycle","prev-cycle","7d","14d","30d","3mo","12mo","custom"],"default":"cycle"},"description":"Window to report. `cycle` / `prev-cycle` resolve to the customer's\nreal billing-period bounds (falling back to a trailing 30 days when\nno invoice exists yet); `7d`…`12mo` are trailing windows; `custom`\nuses `from` / `to`.\n"},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Inclusive start (UTC date). Required when `range=custom`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Inclusive end (UTC date). Required when `range=custom`. Max span 366 days."},{"name":"granularity","in":"query","required":false,"schema":{"type":"string","enum":["day","month","total"],"default":"day"},"description":"Bucketing of the `days` series: `day` (one row per UTC day),\n`month` (one row per calendar month, dated to the 1st), or `total`\n(no series, read `totals`). Does not affect `totals`.\n"},{"name":"groupBy","in":"query","required":false,"schema":{"type":"string","enum":["profile","account"]},"description":"Metering mode. Adds `attribution`: the window's spend split per profile or per account (keys are ids; resolve names via `GET /v1/profiles` / `GET /v1/accounts`)."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string"},"description":"Metering mode (pair with `range`). Project the payload onto this profile's attributed share. Mutually exclusive with `accountId`, and `groupBy` (if given) must be `profile`; 404 when the profile is not in your team (or outside a scoped key's profiles)."},{"name":"accountId","in":"query","required":false,"schema":{"type":"string"},"description":"Metering mode (pair with `range`). Project the payload onto this account's attributed share. Mutually exclusive with `profileId`, and `groupBy` (if given) must be `account`; 404 when the account is not visible to the caller."}],"responses":{"200":{"x-summary":"The usage data was returned: a snapshot without metering parameters, or billed spend by product over the window with them.","description":"Snapshot (no metering params) or billed spend by product over the\nwindow (with metering params).\n","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UsageStats"},{"$ref":"#/components/schemas/UsageMetering"}]}}}},"400":{"description":"Invalid query parameter"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"x-summary":"The billing backend is rate limiting reads: wait the seconds in `Retry-After` and retry.","description":"The billing backend is rate limiting reads (code `rate_limited`). Wait `Retry-After` seconds and retry. Before 1.81.0 this surfaced as a 500.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/usage-stats":{"get":{"x-resource-group":"billing","operationId":"getUsageStats","tags":["Usage"],"summary":"Get plan and usage snapshot (plan, limits, payment status)","deprecated":true,"description":"The plan / quota / payment-status snapshot: current plan name, billing period, plan limits, usage counts, and access state.\n\nIdentical to a bare `GET /v1/usage` call (this path is its deprecated alias).\n\n### Related endpoints\n\n- Billed spend by product: call `GET /v1/usage` with `range` / `granularity` params.\n- The statement view (balance, credits, caps, payment status) lives at `GET /v1/billing`.\n\n### Response shape\n\nThe response shape depends on the account's `billingSystem`:\n\n- Stripe users: per-period `usage.uploads` / `usage.profiles` counters.\n- Usage-based billing users: `usage.connectedAccounts`, `usage.xApiCallsByOperation` (per-operation X API call counts; resolve keys via `GET /v1/billing/x-pricing`), plus a `spend` block with `currentPeriodCents`, `xSpendCents`, and `xSpendLimitCents`.\n\nThe legacy `usage.xApiCalls` 3-tier aggregate is still emitted for back-compat. It excludes the $0.200 URL tier and any future tiers, so new clients should consume `xApiCallsByOperation` only.\n","parameters":[{"name":"reconcile","in":"query","required":false,"schema":{"type":"boolean"},"description":"For Stripe subscription users, `true` forces a subscription\nreconciliation pass even when cached plan data looks complete.\nOmit the parameter, or pass `false`, to use the default\nfirst-time-only reconciliation behavior. Invalid boolean values are\nrejected.\n"}],"responses":{"200":{"description":"Usage stats","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageStats"},"examples":{"stripe":{"summary":"Stripe subscription user","value":{"billingSystem":"stripe","planName":"Pro","billingPeriod":"monthly","signupDate":"2024-01-15T10:30:00Z","billingAnchorDay":15,"limits":{"uploads":500,"profiles":10},"usage":{"uploads":127,"profiles":3,"lastReset":"2024-11-01T00:00:00Z"},"hasAccess":true,"isInvitedUser":false,"autoUpgradeEnabled":false}},"metronome":{"summary":"Usage-based billing user","value":{"billingSystem":"metronome","planName":"Usage-Based","billingPeriod":"monthly","limits":{"uploads":-1,"profiles":-1},"usage":{"connectedAccounts":5,"xApiCalls":{"x_api_005":42,"x_api_010":1,"x_api_015":7},"xApiCallsByOperation":{"posts_read":42,"content_create":7,"content_create_with_url":3,"dm_event_read":1,"dm_interaction_create":1}},"spend":{"currentPeriodCents":1293,"creditsRemainingCents":0,"xSpendCents":94,"xSpendLimitCents":1000},"hasAccess":true,"isInvitedUser":false,"autoUpgradeEnabled":false}}}}}},"400":{"description":"Invalid query parameter"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"x-summary":"The billing backend is rate limiting reads: wait the seconds in `Retry-After` and retry.","description":"The billing backend is rate limiting reads (code `rate_limited`). Wait `Retry-After` seconds and retry. Before 1.81.0 this surfaced as a 500.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/usage/calls":{"get":{"x-resource-group":"billing","operationId":"getCallsUsage","tags":["Usage"],"summary":"Calling usage and cost","description":"Aggregated calling usage across your numbers, both channels\n(WhatsApp Business Calling + regular phone/PSTN): call counts,\nanswered counts, minutes, and cost. Use it for cost visibility or to\nrebill your own customers per number.\n\nCosts come from each call's billing snapshot, so this endpoint always\nagrees with the invoice: `billableUSD` is what Zernio bills;\n`metaUSD` is the WhatsApp per-minute charge Meta bills directly to\nyour WABA (display only, never billed by Zernio).\n\nOptional `groupBy` returns a breakdown by UTC day, by your number, or\nby channel. Defaults to the last 30 days.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Start of the window (inclusive). Default 30 days before `until`."},{"name":"until","in":"query","schema":{"type":"string","format":"date-time"},"description":"End of the window (exclusive). Default now."},{"name":"channel","in":"query","schema":{"type":"string","enum":["whatsapp","pstn"]}},{"name":"number","in":"query","schema":{"type":"string"},"description":"Scope to calls involving this number (typically one of YOUR numbers). E.164, leading + optional."},{"name":"groupBy","in":"query","schema":{"type":"string","enum":["day","number","channel"]}}],"responses":{"200":{"description":"Usage totals (+ breakdown when groupBy is set).","content":{"application/json":{"schema":{"type":"object","properties":{"since":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"},"groupBy":{"type":["string","null"],"enum":["day","number","channel",null]},"totals":{"type":"object","properties":{"calls":{"type":"integer"},"answered":{"type":"integer"},"minutes":{"type":"number"},"billableUSD":{"type":"number","description":"What Zernio bills for these calls."},"metaUSD":{"type":"number","description":"WhatsApp only: Meta's per-minute charge, billed by Meta directly to your WABA. Display only."},"brandedCalls":{"type":"integer","description":"Outbound calls that carried a Branded Calling surcharge."},"brandedCallUSD":{"type":"number","description":"The Branded Calling surcharge on those calls, already inside billableUSD."}}},"groups":{"type":"array","description":"Present (possibly empty) when `groupBy` is set.","items":{"type":"object","properties":{"key":{"type":"string","description":"The group key: a `YYYY-MM-DD` UTC day, one of your numbers, or a channel."},"calls":{"type":"integer"},"answered":{"type":"integer"},"minutes":{"type":"number"},"billableUSD":{"type":"number"},"metaUSD":{"type":"number"},"brandedCalls":{"type":"integer"},"brandedCallUSD":{"type":"number"}}}}}}}}},"400":{"description":"since must be before until"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/usage/sms":{"get":{"x-resource-group":"billing","operationId":"getSmsUsage","tags":["Usage"],"summary":"SMS usage (volumes)","description":"Aggregated SMS/MMS volumes across your numbers: sent, received, and\ntotal message counts, with an optional breakdown by UTC day or by\nnumber. Defaults to the last 30 days.\n\nVolumes only, deliberately: SMS cost is carrier-rated asynchronously\nand billed to your invoice, so per-message cost is not available here.\nCalling usage (GET /v1/usage/calls) does include billable cost.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Start of the window (inclusive). Default 30 days before `until`."},{"name":"until","in":"query","schema":{"type":"string","format":"date-time"},"description":"End of the window (exclusive). Default now."},{"name":"number","in":"query","schema":{"type":"string"},"description":"Scope to one of YOUR SMS-enabled numbers (E.164, leading + optional)."},{"name":"groupBy","in":"query","schema":{"type":"string","enum":["day","number"]}}],"responses":{"200":{"description":"Volume totals (+ breakdown when groupBy is set).","content":{"application/json":{"schema":{"type":"object","properties":{"since":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"},"groupBy":{"type":["string","null"],"enum":["day","number",null]},"totals":{"type":"object","properties":{"sent":{"type":"integer"},"received":{"type":"integer"},"total":{"type":"integer"}}},"groups":{"type":"array","description":"Present (possibly empty) when `groupBy` is set.","items":{"type":"object","properties":{"key":{"type":"string","description":"A `YYYY-MM-DD` UTC day or one of your numbers."},"sent":{"type":"integer"},"received":{"type":"integer"},"total":{"type":"integer"}}}}}}}}},"400":{"description":"since must be before until"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"`number` doesn't match any of your SMS-enabled numbers"}}}},"/v1/posts":{"get":{"x-resource-group":"publishing","operationId":"listPosts","tags":["Posts"],"summary":"List posts","description":"Returns a paginated list of posts. Published posts include platformPostUrl with the public URL on each platform. A query parameter that is not listed here returns 400 naming it and the accepted parameters, so a misspelled filter never silently returns the unfiltered list.","parameters":[{"$ref":"#/components/parameters/PageParam"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":10},"description":"Page size. Values above the maximum return 400 rather than being clamped."},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0},"description":"Row offset. Takes precedence over page when both are sent; the response pagination.page is derived from it."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from a previous response's `pagination.nextCursor`. Returns the next page in the same `sortBy` order and takes precedence over `page` and `offset`.\n\nEach cursor page costs the same however deep it is, unlike `page`/`offset`, which get slower the further you go. Prefer it to walk a long history.\n\n- Send the same filters and `sortBy` as the request that issued it. A cursor from another `sortBy` returns 400.\n- Not available with `sortBy=status` or `sortBy=platform`, or with `source=external`.\n"},{"name":"fields","in":"query","schema":{"type":"string"},"example":"status,scheduledFor,platforms","description":"Comma-separated list of post fields to return. Each post then carries `_id` plus only these fields, which makes large pages much cheaper: leave out `platforms`, `content`, `mediaItems` or `metadata` when you do not need them.\n\nAccepted: `userId`, `title`, `content`, `mediaItems`, `platforms`, `scheduledFor`, `timezone`, `status`, `tags`, `hashtags`, `mentions`, `visibility`, `metadata`, `recycling`, `recycledFromPostId`, `queuedFromProfile`, `queueId`, `createdAt`, `updatedAt`.\n\nAn unknown field returns 400 naming it. `fields=_id` returns ids only. Omit it (or send it empty) for the full post. Not available with `source=external`.\n"},{"name":"updatedSince","in":"query","schema":{"type":"string","format":"date-time"},"example":"2026-10-27T18:00:00Z","description":"Only posts whose `updatedAt` is at or after this ISO 8601 timestamp (an offset or `Z` required).\n\n`updatedAt` moves when the post or any of its platforms changes (an edit, a status change, a platform publishing or failing). To keep a copy in sync, send the time of your previous sync instead of reading every page again.\n\nCombines with the other filters and with `cursor`. Deleted posts are not returned. Not available with `source=external`.\n"},{"name":"source","in":"query","schema":{"type":"string","enum":["zernio","external"],"default":"zernio"},"description":"Which collection to read. `zernio` (default) returns posts authored through Zernio. `external` returns posts synced from the platform (existing/historical posts that were published outside Zernio). Combine with `accountId` and paginate via `page`/`limit` to walk the full synced history (we keep up to the last ~12 months per account)."},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","pending_approval","scheduled","publishing","published","partial","failed","cancelled"]}},{"name":"platform","in":"query","schema":{"type":"string","example":"twitter"}},{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Filter posts to a specific profile (24-char hex ObjectId), including drafts filed under it without platforms. Omit it, or send `all` or an empty value, to list posts across every profile."},{"name":"createdBy","in":"query","schema":{"type":"string"},"description":"Filter posts to those created by a specific team user (24-char hex ObjectId)."},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Zero-padded YYYY-MM-DD, or a full ISO 8601 datetime. An empty value means no date filter; any other malformed value returns 400. The same name the other date-window filters use (ads, analytics)."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"Zero-padded YYYY-MM-DD, or a full ISO 8601 datetime. An empty value means no date filter; any other malformed value returns 400. The same name the other date-window filters use (ads, analytics)."},{"name":"dateFrom","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of fromDate, kept for existing callers"},{"name":"dateTo","in":"query","deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of toDate, kept for existing callers"},{"name":"includeHidden","in":"query","schema":{"type":"boolean","default":false}},{"name":"search","in":"query","schema":{"type":"string"},"description":"Search posts by text content."},{"name":"tags","in":"query","schema":{"type":"string","example":"job,engineering"},"description":"Comma-separated tags (at most 20). Returns only posts carrying every listed tag, matched exactly and case-sensitively against the tags set when the post was created. An empty value means no tag filter. `tag` is accepted as an alias."},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["scheduled-desc","scheduled-asc","created-desc","created-asc","status","platform"],"default":"scheduled-desc"},"description":"Sort order for results."},{"name":"accountId","in":"query","required":false,"schema":{"type":"string"},"description":"Filter posts to those published via a specific account (24-char hex ObjectId)."}],"responses":{"200":{"description":"Paginated posts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostsListResponse"},"examples":{"scheduledPost":{"summary":"Scheduled post (pending publish)","value":{"posts":[{"_id":"65f1c0a9e2b5af0012ab34cd","title":"Launch post","content":"We just launched!","status":"scheduled","scheduledFor":"2024-11-01T10:00:00Z","timezone":"UTC","platforms":[{"platform":"twitter","accountId":{"_id":"64e1f0...","platform":"twitter","username":"@acme","displayName":"Acme Corp","isActive":true},"status":"pending"}],"tags":["launch"],"createdAt":"2024-10-01T12:00:00Z","updatedAt":"2024-10-01T12:00:00Z"}],"pagination":{"page":1,"limit":10,"total":1,"pages":1}}},"publishedPost":{"summary":"Published post with platformPostUrl","value":{"posts":[{"_id":"65f1c0a9e2b5af0012ab34cd","title":"Launch post","content":"We just launched!","status":"published","scheduledFor":"2024-11-01T10:00:00Z","publishedAt":"2024-11-01T10:00:05Z","timezone":"UTC","platforms":[{"platform":"twitter","accountId":{"_id":"64e1f0a9e2b5af0012ab34de","platform":"twitter","username":"@acmecorp","displayName":"Acme Corporation","isActive":true},"status":"published","publishedAt":"2024-11-01T10:00:05Z","platformPostId":"1852634789012345678","platformPostUrl":"https://twitter.com/acmecorp/status/1852634789012345678"},{"platform":"linkedin","accountId":{"_id":"64e1f0a9e2b5af0012ab34ef","platform":"linkedin","username":"acme-corporation","displayName":"Acme Corporation","isActive":true},"status":"published","publishedAt":"2024-11-01T10:00:06Z","platformPostId":"urn:li:share:7123456789012345678","platformPostUrl":"https://www.linkedin.com/feed/update/urn:li:share:7123456789012345678"}],"tags":["launch"],"createdAt":"2024-10-01T12:00:00Z","updatedAt":"2024-11-01T10:00:06Z"}],"pagination":{"page":1,"limit":10,"total":1,"pages":1}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"x-resource-group":"publishing","operationId":"createPost","x-selectedCodeSample":"schedule","x-docs":{"highlights":["Posts over **25/hour** per account are queued, not rejected","Idempotent with **Idempotency-Key**"],"body":{"essentials":[{"field":"content","requirement":"Required for text-only posts"},{"field":"platforms","requirement":"Required unless draft"}],"choice":{"title":"When it publishes","options":[{"label":"Schedule","field":"scheduledFor","request":"schedule","returns":{"status":"201","example":"scheduled","summary":"status scheduled"}},{"label":"Publish now","field":"publishNow","value":true,"request":"publishNow","returns":{"status":"201","example":"immediatePublish","summary":"status published, or 207 when some platforms fail"}},{"label":"Next queue slot","field":"queuedFromProfile","request":"queue","returns":{"status":"201","example":"queueScheduled","summary":"status scheduled, at the slot time"}},{"label":"Draft","field":"isDraft","value":true,"request":"draft","returns":{"status":"201","example":"draft","summary":"status draft"}}]},"groups":[{"title":"Media","fields":["mediaItems"]},{"title":"Per platform","note":"inside each platforms[] entry","fields":["platforms[].customContent","platforms[].customMedia","platforms[].scheduledFor","platforms[].platformSpecificData"]},{"title":"Platform defaults","note":"merged into each matching platforms[] entry","fields":["tiktokSettings","facebookSettings"]},{"title":"Scheduling","fields":["timezone","requiresApproval","queueId","recycling"]},{"title":"Organizing","fields":["title","profileId","tags","hashtags","mentions","metadata","crosspostingEnabled"]},{"title":"Testing","fields":["dryRun"]}]},"responses":{"400":{"retry":false},"401":{"retry":false},"403":{"retry":false}},"related":[{"operationId":"getMediaPresignedUrl","summary":"Upload a file before attaching it in mediaItems."},{"operationId":"getPost","summary":"Read the post and each platform's status."},{"operationId":"retryPost","summary":"Publish again the platforms that failed."},{"href":"/guides/post-lifecycle","summary":"Every status a post moves through."}]},"tags":["Posts"],"summary":"Create post","description":"Create a post, and optionally publish it in the same request. A post published immediately (`publishNow: true`) comes back with `platformPostUrl` in the response.\n\n## Optional content\n\n`content` is optional in four cases:\n\n- media is attached\n- all platforms have `customContent`\n- every platform entry is an X Article (`platformSpecificData.article`)\n- every platform entry is a LinkedIn text-free reshare (`platformSpecificData.reshareUrl` with no text)\n\nSee each platform's schema for media constraints.\n\n## Scheduling\n\nPick one of:\n\n- `scheduledFor`: publish at the scheduled time\n- `publishNow: true`: publish synchronously, inside this request\n- `queuedFromProfile`: publish in the profile's next queue slot\n\nWith none of them and `isDraft` unset, the post is saved as a draft. `platforms` is required unless the post is a draft.\n\nPrecedence:\n\n- `isDraft: true` wins over `publishNow` and `scheduledFor` (the post is saved, never published).\n- `publishNow: true` wins over `scheduledFor`.\n- A `scheduledFor` already in the past is not rejected: the post is published synchronously in the same request, exactly like `publishNow`.\n\n## Idempotency\n\nThree layers of duplicate-protection apply, so safe-to-retry callers (network blips, n8n / Zapier retries, etc.) don't accidentally double-post. They are checked in this order:\n\n1. An `Idempotency-Key` match (200)\n2. Same-`x-request-id` retries (200)\n3. The content-hash dedup (409)\n\n### 1. `Idempotency-Key` (recommended for retries, 24-hour window)\n\nSend an `Idempotency-Key` header (a UUID per logical post, up to 255 characters). Reuse it when you retry after a 5xx, a timeout or a dropped connection.\n\nA retry with the same key within 24 hours returns **HTTP 200** with the original post in the `post` field, and no new post is created.\n\nThe match is on the key alone, not on the body: a retry returns the original post even if its body differs (for example a re-uploaded media URL).\n\nIt covers drafts, and a post that was saved even though the original response was a 5xx or timed out.\n\n- If the first request is still being processed, the retry gets **HTTP 409** with `code: idempotency_conflict` and a `Retry-After` header; retry after that delay.\n- If the first request failed without creating a post, the retry is processed as a new request.\n\nKeys are scoped to your user. Never reuse a key for a different post: that post would not be created, and the earlier one would be returned instead.\n\n### 2. `x-request-id` retry detection (24-hour window)\n\nA request may carry the same `x-request-id` as an earlier one AND collide with it on the content fingerprint below (same account, content and media URLs).\n\nThen we return **HTTP 200** with the original post in the `post` field (or **HTTP 202** with `postId` if the original is still being saved) instead of a 409.\n\nA request with the same `x-request-id` but different content is a new post. When both headers are sent, `Idempotency-Key` wins and `x-request-id` is ignored for matching.\n\nThe official Zernio SDKs auto-generate a unique `x-request-id` per call. On a generic HTTP client (curl, n8n's HTTP node, Zapier, custom code), either:\n\n- Set a unique `x-request-id` per logical call (UUIDv4 is fine)\n- Or omit the header, and we'll treat each request as new\n\n### 3. Content-hash dedup (24-hour window)\n\nIndependently, we hash `(platform, accountId, content + media URLs)` and reject duplicates within 24 hours with **HTTP 409**. This catches genuine \"same content posted twice to the same account\" cases regardless of `x-request-id`.\n\nThe response carries `error`, `accountId`, `platform`, and `existingPostId` so you can find the original.\n\nTo intentionally re-post identical content within 24h, change something (the caption, the media, the account), because the dedup is keyed on the full content fingerprint.\n","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Optional client-generated key (a UUID per logical post) that makes retries safe. Reuse it on every retry of the same post, especially after a 5xx or a timeout.\n\n- A retry with the same key within 24 hours returns the original post (HTTP 200), whatever its body.\n- While the original is still processing, it returns 409 `idempotency_conflict` with `Retry-After`.\n- Longer than 255 characters returns 400.\n\nTakes precedence over `x-request-id`. See the operation description for the full contract.\n"},{"name":"x-request-id","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Optional client-generated request identifier. SDKs set it automatically.\n\nA request with the same value as an earlier one within 24 hours that also matches its content fingerprint (same account, content and media URLs) returns the original post (HTTP 200) instead of a duplicate-content 409.\n\nIt does not protect a retry whose body differs; use `Idempotency-Key` for that. See the operation description for the full idempotency contract.\n"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Stored on the post for reference/display only. This field is NOT used as the video title when publishing. To set a YouTube video title, use platformSpecificData.title on the youtube platform target (falls back to the first line of content when omitted)."},"content":{"type":"string","description":"Post caption/text. Optional when media is attached, all platforms have customContent, every platform entry is an X Article (platformSpecificData.article), or every platform entry is a LinkedIn text-free reshare (platformSpecificData.reshareUrl with no text). Required for other text-only posts."},"mediaItems":{"type":"array","description":"Media attached to every platform in the request (a platform entry can override it with `customMedia`).\n\n- Each entry needs a publicly reachable HTTPS `url`.\n- `type` (image, video, gif, document) is inferred from the URL extension when omitted; a `type` that contradicts the extension is rejected with 400.\n- Upload files with `POST /v1/media/presign` first.\n- Per-platform size, duration and format limits are listed on each platform schema.\n","items":{"$ref":"#/components/schemas/MediaItem"}},"platforms":{"type":"array","description":"Target platforms and accounts for this post. Required for non-draft posts (returns 400 if empty). Drafts can omit platforms.","items":{"type":"object","required":["platform","accountId"],"properties":{"platform":{"type":"string","example":"twitter"},"accountId":{"type":"string"},"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. When omitted, the top-level scheduledFor is used."},"platformSpecificData":{"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"}]}}}},"scheduledFor":{"type":"string","format":"date-time","description":"When to publish. Required unless `publishNow` is true, `queuedFromProfile` is set, or the post is a draft. Ignored when `publishNow` is true.\n\nAn ISO 8601 value:\n\n- With a `Z` or offset (`2026-01-15T10:00:00Z`, `2026-01-15T11:00:00+01:00`): taken as-is.\n- Without one (`2026-01-15T10:00:00` or `2026-01-15 10:00`): read as local time in `timezone`.\n\nA value already in the past is published synchronously in the same request.\n"},"publishNow":{"type":"boolean","default":false,"description":"Publish to every platform synchronously in this request instead of scheduling; the response then carries each platform result and `platformPostUrl`, with HTTP 207 when some platforms failed. Takes precedence over `scheduledFor`; ignored when `isDraft` is true."},"isDraft":{"type":"boolean","default":false,"description":"When true, saves the post as a draft. When none of scheduledFor, publishNow, or queuedFromProfile are provided, the post defaults to draft automatically."},"requiresApproval":{"type":"boolean","default":false,"description":"When true, saves the post as pending_approval instead of scheduled. Needs scheduledFor, at the root or on every platform; cannot be combined with isDraft, publishNow, queuedFromProfile or queueId. The post publishes only after POST /v1/posts/{postId}/review approves it; approving after the scheduled time publishes within a couple of minutes."},"dryRun":{"type":"boolean","default":false,"description":"TikTok only. Preview whether each `tiktok` entry in `platforms` could publish right now under the TikTok Direct Post daily limits, without creating, scheduling or publishing anything.\n\nNo post is persisted and no upload slot is claimed, so it can be repeated freely. The request still goes through auth, the payment gate, body validation and the same account access checks as a real create (it can return 400 or 403).\n\nReturns HTTP 200 with `{ dryRun: true, canPublish, tiktok: [...] }` instead of 201. Only `tiktok` entries are evaluated; other platforms are ignored. A body with no `tiktok` entry is rejected with 400 `invalid_field_value` on `platforms`.\n\nAlways `canPublish: true` (not subject to the limit):\n\n- Entries with `platformSpecificData.tiktokSettings.draft: true` (Creator Inbox upload).\n- Accounts connected through the TikTok for Business app. On those, a dry run confirms the request is well-formed rather than gating it.\n"},"timezone":{"type":"string","description":"IANA timezone (`Europe/Madrid`, `America/New_York`) used to interpret a `scheduledFor` (root or per-platform) that carries no `Z` or offset. Stored on the post. No effect on values that already carry one.\n\n**When omitted:** the post takes its profile's `timezone` (the queue's profile for a queued post, else the profile its accounts share). UTC when there is none, or the accounts sit on profiles with different timezones.\n\nAn unknown name returns 400 when `scheduledFor` is set.\n"},"tags":{"type":"array","description":"Tags/keywords. YouTube constraints: each tag max 100 chars, combined max 500 chars, duplicates auto-removed.","items":{"type":"string"}},"hashtags":{"type":"array","description":"Stored for reference only. Hashtags are NOT automatically appended to the caption when publishing. Include hashtags directly in the content field (platforms like Instagram only support hashtags as caption text). For YouTube keywords, use the tags field instead.","items":{"type":"string"}},"mentions":{"type":"array","description":"Stored for reference only. Publishing does not create mentions from this field.","items":{"type":"string"}},"crosspostingEnabled":{"type":"boolean","default":true,"description":"Stored on the post and echoed back on reads. Publishing does not branch on it: every entry in `platforms` is published regardless, so treat it as a label for your own tooling."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form key/value pairs of your own, stored on the post and returned on reads and in webhook payloads. Zernio also writes the bookkeeping keys `usageCounted`, `usageRefunded` and `hidden` into this object; do not set them, and they are stripped from webhook payloads."},"tiktokSettings":{"$ref":"#/components/schemas/TikTokPlatformData","description":"Root-level TikTok settings applied to the TikTok platforms sent in the same request. Merged into each platform's platformSpecificData, with platform-specific settings taking precedence."},"facebookSettings":{"$ref":"#/components/schemas/FacebookSettings","description":"Root-level Facebook settings applied to the Facebook platforms sent in the same request. Merged into each platform's platformSpecificData.facebookSettings, with platform-specific settings taking precedence."},"recycling":{"$ref":"#/components/schemas/RecyclingConfig"},"queuedFromProfile":{"type":"string","description":"Profile ID to schedule via queue. When provided without scheduledFor, the post is auto-assigned to the next available slot. Do not call /v1/queue/next-slot and use that time in scheduledFor, as that bypasses queue locking."},"queueId":{"type":"string","description":"Specific queue ID to use when scheduling via queue.\nOnly used when queuedFromProfile is also provided.\nIf omitted, uses the profile's default queue.\n"},"profileId":{"type":"string","description":"Files a draft with no platforms under this profile so it lists under ?profileId= and profile-scoped API keys. Ignored when platforms are set. When promoting the draft via PUT, send platforms, isDraft false and scheduledFor again."}}},"examples":{"schedule":{"summary":"Schedule for a time","value":{"content":"We just launched!","platforms":[{"platform":"twitter","accountId":"64e1f0a9e2b5af0012ab34cd"}],"scheduledFor":"2024-11-01T10:00:00Z","timezone":"UTC"}},"publishNow":{"summary":"Publish now","value":{"content":"We just launched!","platforms":[{"platform":"twitter","accountId":"64e1f0a9e2b5af0012ab34cd"}],"publishNow":true}},"queue":{"summary":"Next queue slot","value":{"content":"We just launched!","platforms":[{"platform":"twitter","accountId":"64e1f0a9e2b5af0012ab34cd"}],"queuedFromProfile":"64f0a1b2c3d4e5f6a7b8c9d0"}},"draft":{"summary":"Save as a draft","value":{"content":"We just launched!","isDraft":true}},"twitterArticle":{"summary":"Publish a long-form X Article","description":"Creates an X Article draft and publishes it. This normally makes two\nbillable X API calls at $0.010 each ($0.020 total). The account must\nbe eligible for X Articles (X Premium+). Article media is supplied as\npublic URLs; Zernio uploads it to X and builds the native media shape.\n","value":{"platforms":[{"platform":"twitter","accountId":"64e1f0a9e2b5af0012ab34cd","platformSpecificData":{"article":{"title":"Building a better publishing workflow","mode":"publish","cover":{"url":"https://cdn.example.com/article-cover.jpg"},"content_state":{"blocks":[{"type":"header-one","text":"A reliable publishing workflow"},{"type":"unstyled","text":"Long-form publishing should be observable. Read the implementation notes.","inline_style_ranges":[{"offset":0,"length":9,"style":"bold"}],"entity_ranges":[{"key":0,"offset":52,"length":20}]},{"type":"atomic","text":" ","entity_ranges":[{"key":1,"offset":0,"length":1}]}],"entities":[{"key":"0","value":{"type":"link","mutability":"mutable","data":{"url":"https://example.com/implementation-notes"}}},{"key":"1","value":{"type":"image","mutability":"immutable","data":{"url":"https://cdn.example.com/workflow.png","caption":"The publishing stages"}}}]}}}}],"publishNow":true}},"twitterArticleDraft":{"summary":"Save an X Article as a platform draft","description":"Creates only the X Article draft ($0.010) and does not publish it publicly.","value":{"platforms":[{"platform":"twitter","accountId":"64e1f0a9e2b5af0012ab34cd","platformSpecificData":{"article":{"title":"Draft product update","mode":"draft","content_state":{"blocks":[{"type":"unstyled","text":"This Article is ready for final review."}],"entities":[]}}}}],"publishNow":true}},"facebookDraft":{"summary":"Facebook draft post (visible in Publishing Tools)","value":{"content":"Draft post for review before publishing","platforms":[{"platform":"facebook","accountId":"64e1f0a9e2b5af0012ab34cd"}],"publishNow":true,"facebookSettings":{"draft":true}}},"facebookCarousel":{"summary":"Facebook multi-link carousel post","description":"Posts a 2-10 card carousel where each image has its own click-through link\nand optional headline. mediaItems and carouselCards must have the same\nlength, in the same order. Images only (no video cards).\n","value":{"content":"Check out our new inventory","mediaItems":[{"url":"https://cdn.example.com/car-1.jpg","type":"image"},{"url":"https://cdn.example.com/car-2.jpg","type":"image"},{"url":"https://cdn.example.com/car-3.jpg","type":"image"}],"platforms":[{"platform":"facebook","accountId":"64e1f0a9e2b5af0012ab34cd"}],"publishNow":true,"facebookSettings":{"carouselLink":"https://example.com/inventory","carouselCards":[{"link":"https://example.com/inventory/car-1","name":"2024 Sedan","description":"Low miles"},{"link":"https://example.com/inventory/car-2","name":"2023 SUV","description":"Certified pre-owned"},{"link":"https://example.com/inventory/car-3","name":"2024 Truck","description":"Loaded"}]}}},"facebookTextBackground":{"summary":"Facebook colored-background text post","description":"Renders the post as large text on a Facebook-defined colored background.\nText-only: mediaItems and carouselCards are rejected, and contentType\nmust not be story or reel.\n","value":{"content":"We just shipped something big.","platforms":[{"platform":"facebook","accountId":"64e1f0a9e2b5af0012ab34cd"}],"publishNow":true,"facebookSettings":{"textFormatPresetId":"1881421442117417"}}},"recyclingPost":{"summary":"Post with weekly recycling and content variations","value":{"content":"Check out our evergreen guide!","platforms":[{"platform":"twitter","accountId":"64e1f0a9e2b5af0012ab34cd"}],"scheduledFor":"2025-06-01T10:00:00Z","recycling":{"gap":2,"gapFreq":"week","expireCount":6,"contentVariations":["Check out our evergreen guide!","Don't miss our essential guide!","Our most popular guide, updated!"]}}},"tiktokPhotoCarousel":{"summary":"TikTok photo carousel (Creator Inbox draft)","description":"Sends photos to TikTok Creator Inbox as a draft. The creator receives an inbox\nnotification and completes the post via TikTok's editing flow. Uses draft: true\nwhich maps to TikTok API post_mode MEDIA_UPLOAD. Note: publish_type is not a\nsupported field; use draft instead.\n","value":{"content":"Check out these photos!","mediaItems":[{"type":"image","url":"https://example.com/photo1.jpg"},{"type":"image","url":"https://example.com/photo2.jpg"}],"platforms":[{"platform":"tiktok","accountId":"64e1f0a9e2b5af0012ab34cd"}],"tiktokSettings":{"draft":true,"privacyLevel":"PUBLIC_TO_EVERYONE","allowComment":true,"photoCoverIndex":0,"autoAddMusic":false,"contentPreviewConfirmed":true,"expressConsentGiven":true}}},"tiktokPhotoDirect":{"summary":"TikTok photo carousel (direct publish)","description":"Publishes photos directly to TikTok. With draft omitted or false, the post is\npublished immediately via TikTok API post_mode DIRECT_POST.\n","value":{"content":"Check out these photos!","mediaItems":[{"type":"image","url":"https://example.com/photo1.jpg"},{"type":"image","url":"https://example.com/photo2.jpg"}],"platforms":[{"platform":"tiktok","accountId":"64e1f0a9e2b5af0012ab34cd"}],"tiktokSettings":{"privacyLevel":"PUBLIC_TO_EVERYONE","allowComment":true,"photoCoverIndex":0,"autoAddMusic":false,"contentPreviewConfirmed":true,"expressConsentGiven":true}}},"tiktokVideo":{"summary":"TikTok video post (direct publish)","value":{"content":"New video is live!","mediaItems":[{"type":"video","url":"https://example.com/video.mp4"}],"platforms":[{"platform":"tiktok","accountId":"64e1f0a9e2b5af0012ab34cd"}],"tiktokSettings":{"privacyLevel":"PUBLIC_TO_EVERYONE","allowComment":true,"allowDuet":true,"allowStitch":true,"commercialContentType":"none","contentPreviewConfirmed":true,"expressConsentGiven":true}}},"tiktokVideoDraft":{"summary":"TikTok video post (Creator Inbox draft)","description":"Sends a video to TikTok Creator Inbox as a draft. Video drafts use a dedicated\nTikTok endpoint (/v2/post/publish/inbox/video/init/) that only accepts source_info,\nso post_info fields (privacyLevel, allowComment, etc.) are set by the creator\nduring TikTok's editing flow.\n","value":{"content":"New video draft!","mediaItems":[{"type":"video","url":"https://example.com/video.mp4"}],"platforms":[{"platform":"tiktok","accountId":"64e1f0a9e2b5af0012ab34cd"}],"tiktokSettings":{"draft":true,"contentPreviewConfirmed":true,"expressConsentGiven":true}}},"multiPlatform":{"summary":"Multi-platform post (X + LinkedIn)","value":{"content":"We just launched our new product!","mediaItems":[{"type":"image","url":"https://example.com/launch.jpg"}],"platforms":[{"platform":"twitter","accountId":"64e1f0a9e2b5af0012ab34cd"},{"platform":"linkedin","accountId":"64e1f0a9e2b5af0012ab34ef"}],"scheduledFor":"2024-11-01T10:00:00Z","timezone":"America/New_York"}}}}}},"responses":{"200":{"x-summary":"Nothing was created because this was a dry-run preview or an idempotent retry that returns the original post.","description":"Nothing was created. Either a dryRun preview (TikTok only), which deliberately carries no\nnumeric cap detail, only a per-account go/no-go and a reason; or a retry matched by\n`Idempotency-Key` or `x-request-id`, which returns the original post\n(`PostCreateResponse`, with `message: \"Post already exists (idempotent retry)\"`).\n\nA newly created post is always a 201.\n","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/TikTokDryRunVerdict"},{"$ref":"#/components/schemas/PostCreateResponse"}]}}}},"201":{"description":"Post created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostCreateResponse"},"examples":{"scheduled":{"summary":"Scheduled post (URLs populated after publish time)","value":{"post":{"_id":"65f1c0a9e2b5af0012ab34cd","title":"Launch post","content":"We just launched!","status":"scheduled","scheduledFor":"2024-11-01T10:00:00Z","timezone":"UTC","platforms":[{"platform":"twitter","accountId":{"_id":"64e1f0...","platform":"twitter","username":"@acme","displayName":"Acme Corp","isActive":true},"status":"pending"}]},"message":"Post scheduled successfully"}},"immediatePublish":{"summary":"Immediate post with publishNow=true (URLs included)","value":{"post":{"_id":"65f1c0a9e2b5af0012ab34cd","title":"Launch post","content":"We just launched!","status":"published","publishedAt":"2024-11-01T10:00:05Z","timezone":"UTC","platforms":[{"platform":"twitter","accountId":{"_id":"64e1f0a9e2b5af0012ab34de","platform":"twitter","username":"@acmecorp","displayName":"Acme Corporation","isActive":true},"status":"published","publishedAt":"2024-11-01T10:00:05Z","platformPostId":"1852634789012345678","platformPostUrl":"https://twitter.com/acmecorp/status/1852634789012345678"},{"platform":"linkedin","accountId":{"_id":"64e1f0a9e2b5af0012ab34ef","platform":"linkedin","username":"acme-corporation","displayName":"Acme Corporation","isActive":true},"status":"published","publishedAt":"2024-11-01T10:00:06Z","platformPostId":"urn:li:share:7123456789012345678","platformPostUrl":"https://www.linkedin.com/feed/update/urn:li:share:7123456789012345678"}]},"message":"Post published successfully"}},"queueScheduled":{"summary":"Post scheduled via queue (using queuedFromProfile)","value":{"post":{"_id":"65f1c0a9e2b5af0012ab34cd","content":"Scheduled via queue!","status":"scheduled","scheduledFor":"2024-11-01T09:00:00Z","timezone":"America/New_York","queuedFromProfile":"64f0a1b2c3d4e5f6a7b8c9d0","queueId":"64f0a1b2c3d4e5f6a7b8c9d1","platforms":[{"platform":"linkedin","accountId":{"_id":"64e1f0...","platform":"linkedin","username":"acme-corp","displayName":"Acme Corp","isActive":true},"status":"pending"}]},"message":"Post scheduled successfully"}},"draft":{"summary":"Draft post (nothing is published)","value":{"post":{"_id":"65f1c0a9e2b5af0012ab34cd","content":"We just launched!","status":"draft","platforms":[]},"message":"Draft saved successfully"}}}}}},"207":{"x-summary":"The post was created but publishing did not fully succeed: branch on `post.status` to tell partial, failed and scheduled outcomes apart.","description":"The post was created, but the inline publish (`publishNow: true`, or a `scheduledFor` that is already due) did not fully succeed.\n\n**207 is a 2xx status.** `fetch(...).ok` is `true` and axios' default `validateStatus` resolves, so a client that only checks for success reads this as a published post. Branch on the status code explicitly.\n\nTell the outcomes apart with `post.status`:\n\n- `partial`: at least one platform published and at least one failed. Per-platform detail is in `platformResults` and `post.platforms[]`.\n- `failed`: no platform published. Terminal; nothing will be retried. Read `platforms[].errorMessage`, `platforms[].errorCategory` and `platforms[].errorSource` to decide whether the caller, the platform or Zernio must act.\n- `scheduled`: every platform hit a transient error and was reset to `pending`. Zernio retries automatically. This is **not** a failure; do not surface it to an end user as one.\n\nA publish attempt that aborted before it started (for example the post was already being processed) reports none of the three: `post.status` is unchanged and `platformResults` is absent. Read `error` and `post.platforms[]`, which is always present.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostPublishIncompleteResponse"},"examples":{"allPlatformsFailed":{"summary":"Every platform failed (post.status is failed, terminal)","value":{"post":{"_id":"6a9e43f7fd28fe46ce033d98","content":"We just launched!","status":"failed","platforms":[{"platform":"facebook","status":"failed","errorMessage":"Facebook needs you to confirm your identity before you can publish as this Page. Open the Facebook mobile app, go to this Page, and complete the identity confirmation, then try again.","errorCategory":"platform_rejected","errorSource":"platform"}]},"message":"Post created but publishing failed","error":"All platforms failed","platformResults":[{"platform":"facebook","status":"failed","error":"Facebook needs you to confirm your identity before you can publish as this Page. Open the Facebook mobile app, go to this Page, and complete the identity confirmation, then try again."}]}},"temporaryErrorsWillRetry":{"summary":"Transient errors (post.status is scheduled, Zernio retries)","value":{"post":{"_id":"6a9e43f7fd28fe46ce033d99","content":"We just launched!","status":"scheduled","platforms":[{"platform":"instagram","status":"pending"}]},"message":"Post created but publishing failed","error":"Publishing encountered temporary errors. The post will be retried automatically.","platformResults":[{"platform":"instagram","status":"pending","error":null}]}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"object","properties":{"mentions":{"type":"array","items":{"$ref":"#/components/schemas/LinkedInMentionIssue"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"A target account is disconnected, ads-only, over the profile limit or not yours: reconnect it or connect it for posting.","description":"Forbidden. Distinguish by the `code` field:\n\n- `ACCOUNT_DISCONNECTED`: a target account's platform connection is no longer active (token expired or revoked, or disconnected). Reconnect it, then refresh account IDs from `GET /v1/accounts` (connection state is in `isActive`). The disconnect is also emitted as the `account.disconnected` webhook event.\n- `ACCOUNT_NOT_ENABLED_FOR_POSTING`: a target account was connected for ads only (`enabled: false`). Connect it as a posting account (it then counts as a connected account), then refresh account IDs from `GET /v1/accounts`.\n- `PROFILE_OVER_LIMIT`: a target account belongs to a profile beyond the plan's profile limit.\n- No `code`: a target `accountId` does not belong to the authenticated user (or is outside the API key's profile scope).\n","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Account 6a0f6d2e520992756d96bb6c (facebook \"My Page\") is disconnected and cannot be posted to. Facebook tokens expired. Please reconnect your Facebook account. After reconnecting, refresh your account IDs from GET /v1/accounts."},"code":{"type":"string","enum":["ACCOUNT_DISCONNECTED","ACCOUNT_NOT_ENABLED_FOR_POSTING","PROFILE_OVER_LIMIT"],"description":"Stable machine-readable cause. Absent for ownership failures."}}}}}},"409":{"x-summary":"The same content went to this account within a day, or the key is still processing: change the content or retry later.","description":"Duplicate content detected. Returned when the requested post matches an existing one on `(platform, accountId, content-hash)` within the last 24 hours, AND the request was NOT an `x-request-id` retry. Distinct from same-`x-request-id` retries (which return HTTP 200 with the original post; see operation description for the idempotency contract).\n\nAlso returned with `code: idempotency_conflict` and a `Retry-After` header when a request with the same `Idempotency-Key` is still being processed. Retry after the delay to get the original post.\n\nBody fields:\n- `error`: human-readable message\n- `details.accountId`: the account that already has this content\n- `details.platform`: the platform that already has this content\n- `details.existingPostId`: Zernio `_id` of the original post\n\nTo intentionally re-post identical content within 24h, vary the content fingerprint (change the caption, swap a media item, or use a different account). To avoid 409s caused by retry loops, set a unique `x-request-id` per logical request. See `parameters.x-request-id` above.\n","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"This exact content is already scheduled, publishing, or was posted to this account within the last 24 hours."},"details":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string"},"existingPostId":{"type":"string"}}}}}}}},"429":{"x-summary":"A rate limit was hit, such as the API limit or an account cooldown: wait and retry later.","description":"Rate limit exceeded. Possible causes: API rate limit, account cooldown, or daily platform limits.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object","description":"Additional context about the rate limit"}}}}},"headers":{"Retry-After":{"description":"Seconds until the rate limit resets (for API rate limits)","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The rate limit ceiling","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds since epoch) when the next slot frees up in the sliding window","schema":{"type":"integer"}}}},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/v1/posts/sync-external":{"post":{"x-resource-group":"publishing","operationId":"syncExternalPosts","tags":["Analytics"],"x-platforms":["instagram","facebook","tiktok","youtube","twitter","threads","pinterest","reddit","bluesky","googlebusiness","linkedin"],"summary":"Sync an external post","description":"Fetch an account's latest external posts (published directly on the platform, not through Zernio) on demand. A newly published post is then retrievable within seconds instead of waiting for the background sync, which refreshes each account at most every ~90 minutes.\n\nPrimary use case: verifying a submitted post. When a user publishes on the platform and immediately pastes the post URL into your app, call this with `accountId` plus `url` (or `postId`) to confirm the post exists and return its metadata.\n\n### Behavior\n\n- Account access and connection state are checked before any platform call, including requests inside the debounce window.\n- Inactive accounts or accounts marked `needsReconnection` return `409` with code `ads_connection_required`. Stop scheduled retries for that account until it is reconnected, then read `GET /v1/accounts` for its current account ID.\n- For connected accounts, we fetch the latest posts live from the platform, then match and return the submitted post.\n- Requests are debounced per account (~15s): if the account was synced inside that window, the live fetch is skipped.\n\n### Account and platforms\n\n`accountId` is required, because a post URL or id alone cannot be resolved to an account. The account must be connected to Zernio (we use its token to read the platform).\n\nSupported for every platform with a listing API: Instagram, Facebook, TikTok, YouTube, X, Threads, Pinterest, Reddit, Bluesky, Google Business Profile, and LinkedIn organization accounts.\n\n### Locating the post\n\n`url` accepts any format the platform uses, for example:\n\n- `instagram.com/p/…`, `instagram.com/reel/…`\n- `youtu.be/…`, `youtube.com/shorts/…`\n- `tiktok.com/@user/video/…`, `vm.tiktok.com` short links\n- `pinterest.com/pin/…` on any regional domain, and `pin.it` short links\n\nPass `postId` (the platform media/video/pin id) as an alternative locator.\n\n### LinkedIn personal profiles\n\nLinkedIn has no listing API for personal profiles, so a `url` is REQUIRED and imports that single post. Pass any LinkedIn post URL (`linkedin.com/posts/…`, `linkedin.com/feed/update/urn:li:activity:…`) or a `urn:li:share:…` / `urn:li:ugcPost:…` URN.\n\nIt works for posts published outside Zernio and before the account was connected, at any age. The post must be authored by the connected member.\n\nImported posts return full analytics (impressions, reach, reactions, comments, reshares, saves) and keep refreshing on the background analytics cycle. They carry no content/media, since LinkedIn does not expose them for personal profiles.\n\n`publishedAt` comes from the post id:\n\n- An activity URL (`linkedin.com/feed/update/urn:li:activity:…`) carries the publication time.\n- A `urn:li:share:…` / `urn:li:ugcPost:…` URN only carries the creation time, which is earlier for a post scheduled in another tool.\n\nPass the activity URL for the exact publication date. Importing it again for a post already imported by its URN corrects `publishedAt` on the same record.\n\nRight after an import, the per-post `GET /v1/analytics?postId=` read can show zeros for a few minutes while the metrics are ingested. This endpoint's response carries the fetched values immediately.\n\n### TikTok Business accounts\n\nA `postId` or TikTok `url` that the listing has not stored is fetched from TikTok and imported as an external post, at any age, with its current metrics.\n\n### Analytics delay\n\nPost-level analytics (reach, impressions) still carry the platform's own delay (e.g. ~24h on Instagram). This endpoint confirms the post exists and returns its metadata plus basic engagement (likes, comments), not delayed insights.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"SocialAccount ID whose posts to sync. Must be connected to Zernio."},"url":{"type":"string","description":"The post URL to locate. Optional. Provide `url` or `postId` to return a specific post; omit both to refresh and return the account's recent posts."},"postId":{"type":"string","description":"The platform post/media/video id to locate, as an alternative to `url`. Optional."}}}}}},"responses":{"200":{"x-summary":"The sync finished and returns the matched post, or the account's freshly synced recent posts when no post was named.","description":"Sync result. When `url` or `postId` is provided, returns the matched post (or `found: false`). When neither is provided, returns the account's freshly-synced recent posts.\n","content":{"application/json":{"schema":{"type":"object","properties":{"synced":{"type":"object","properties":{"postsFound":{"type":"integer","description":"Posts returned by the platform listing during the on-demand sync"},"postsSynced":{"type":"integer","description":"Posts inserted or updated in Zernio"},"skipped":{"type":"boolean","description":"True when the account was synced within the debounce window and no live fetch ran."}}},"found":{"type":"boolean","description":"Present only when a locator (`url`/`postId`) was provided: whether the post was found."},"post":{"description":"The matched external post, or null when not found. Present only when a locator was provided.","oneOf":[{"$ref":"#/components/schemas/ExternalPostSummary"},{"type":"null"}]},"posts":{"type":"array","description":"The account's recent external posts. Present only when no locator was provided.","items":{"$ref":"#/components/schemas/ExternalPostSummary"}}}}}}},"400":{"description":"Invalid request (e.g. `accountId` missing or malformed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"x-summary":"The platform authorization has expired: reconnect the account and retry.","description":"The platform authorization has expired. Reconnect the account."},"403":{"x-summary":"The API key lacks access to this account or the platform denied access: check the key's scope and the account's platform access.","description":"The API key lacks access to this account or the platform denied access. For X accounts it returns X_ANALYTICS_NOT_ENABLED when X analytics is not enabled for the account, or PAYMENT_REQUIRED when X access is paused for failed billing."},"404":{"description":"Account not found (or not owned by the authenticated user)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"x-summary":"The account is inactive or needs reconnection: stop scheduled retries until you reconnect it.","description":"The account is inactive or needs reconnection. Stop scheduled retries until it is reconnected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"This account needs reconnection. Reconnect the account, then read GET /v1/accounts for its current account ID before retrying.","type":"invalid_request_error","code":"ads_connection_required","param":"accountId"}}}},"502":{"$ref":"#/components/responses/UpstreamFailure"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/v1/posts/{postId}":{"get":{"x-resource-group":"publishing","operationId":"getPost","tags":["Posts"],"summary":"Get post","description":"Fetch a single post by ID. For published posts, this returns platformPostUrl for each platform.\n","parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Post","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostGetResponse"},"examples":{"scheduledPost":{"summary":"Scheduled post (pending)","value":{"post":{"_id":"65f1c0a9e2b5af0012ab34cd","title":"Launch post","content":"We just launched!","status":"scheduled","scheduledFor":"2024-11-01T10:00:00Z","platforms":[{"platform":"twitter","accountId":{"_id":"64e1f0...","platform":"twitter","username":"@acme","displayName":"Acme Corp","isActive":true},"status":"pending"}]}}},"publishedPost":{"summary":"Published post with platformPostUrl","value":{"post":{"_id":"65f1c0a9e2b5af0012ab34cd","title":"Launch post","content":"We just launched!","status":"published","publishedAt":"2024-11-01T10:00:05Z","platforms":[{"platform":"twitter","accountId":{"_id":"64e1f0a9e2b5af0012ab34de","platform":"twitter","username":"@acmecorp","displayName":"Acme Corporation","isActive":true},"status":"published","publishedAt":"2024-11-01T10:00:05Z","platformPostId":"1852634789012345678","platformPostUrl":"https://twitter.com/acmecorp/status/1852634789012345678"},{"platform":"linkedin","accountId":{"_id":"64e1f0a9e2b5af0012ab34ef","platform":"linkedin","username":"acme-corporation","displayName":"Acme Corporation","isActive":true},"status":"published","publishedAt":"2024-11-01T10:00:06Z","platformPostId":"urn:li:share:7123456789012345678","platformPostUrl":"https://www.linkedin.com/feed/update/urn:li:share:7123456789012345678"}]}}},"failedPost":{"summary":"Failed post with error details","value":{"post":{"_id":"65f1c0a9e2b5af0012ab34cd","content":"This post failed to publish","status":"failed","platforms":[{"platform":"instagram","accountId":{"_id":"64e1f0a9e2b5af0012ab34de","platform":"instagram","username":"acmecorp","isActive":false},"status":"failed","errorMessage":"Instagram access token has expired. Please reconnect your account.","errorCategory":"auth_expired","errorSource":"user"}]}}},"partialPost":{"summary":"Partial success (some platforms failed)","value":{"post":{"_id":"65f1c0a9e2b5af0012ab34cd","content":"Launch announcement!","status":"partial","platforms":[{"platform":"twitter","accountId":{"_id":"64e1f0a9e2b5af0012ab34de","platform":"twitter","username":"@acmecorp","isActive":true},"status":"published","publishedAt":"2024-11-01T10:00:05Z","platformPostId":"1852634789012345678","platformPostUrl":"https://twitter.com/acmecorp/status/1852634789012345678"},{"platform":"threads","accountId":{"_id":"64e1f0a9e2b5af0012ab34ef","platform":"threads","username":"acmecorp","isActive":true},"status":"failed","errorMessage":"Post text exceeds the 500 character limit for Threads.","errorCategory":"user_content","errorSource":"user"}]}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"x-resource-group":"publishing","operationId":"updatePost","tags":["Posts"],"summary":"Update post","description":"Update an existing post. Draft, scheduled, failed, partial, and cancelled posts can be edited. Published posts can only have their recycling config updated.\n\nTo promote a draft to scheduled, send `isDraft: false` together with `scheduledFor` (or `publishNow: true`, or `queuedFromProfile`). If `isDraft` is omitted the post keeps its current draft status, so sending only `scheduledFor` to a draft returns 200 but the post remains a draft.\n\nNon-draft updates run the same per-platform validation as post creation (media requirements, platform-specific field rules, etc.) against the resulting platforms, returning 400 on failure.\n","parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Stored on the post for reference/display only. This field is NOT used as the video title when publishing. To set a YouTube video title, use platformSpecificData.title on the youtube platform target (falls back to the first line of content when omitted)."},"content":{"type":"string"},"mediaItems":{"type":"array","items":{"$ref":"#/components/schemas/MediaItem"}},"platforms":{"type":"array","description":"Target platforms and accounts for this post. Each item must include platform and accountId.","items":{"type":"object","required":["platform","accountId"],"properties":{"platform":{"type":"string","example":"twitter"},"accountId":{"type":"string"},"customContent":{"type":"string","description":"Platform-specific text override."},"customMedia":{"type":"array","items":{"$ref":"#/components/schemas/MediaItem"}},"scheduledFor":{"type":"string","format":"date-time","description":"Optional per-platform scheduled time override. It is kept when a top-level scheduledFor is also sent, except a date sent back unchanged (same instant, or the same wall-clock time in the post's previous timezone) that matched the post scheduled time or is already past, which follows the new top-level scheduledFor."},"platformSpecificData":{"type":"object","additionalProperties":true,"description":"A <platform>Settings namespace (e.g. facebookSettings, tiktokSettings) omitted from the request is preserved from the stored post. Sending the key replaces the whole namespace; it is not deep-merged."}}}},"scheduledFor":{"type":"string","format":"date-time"},"publishNow":{"type":"boolean","default":false},"isDraft":{"type":"boolean","description":"When omitted, the post keeps its current draft status. Send `false` to promote a draft to scheduled (combined with `scheduledFor`, `publishNow`, or a queue)."},"requiresApproval":{"type":"boolean","description":"Send true on a draft to submit it for approval: it becomes pending_approval and publishes only after POST /v1/posts/{postId}/review approves it. Cannot be combined with isDraft, publishNow, queuedFromProfile or queueId. Returns 409 when the post is not a draft."},"timezone":{"type":"string"},"visibility":{"type":"string","enum":["public","private","unlisted"]},"tags":{"type":"array","items":{"type":"string"}},"hashtags":{"type":"array","description":"Stored for reference only. Hashtags are NOT automatically appended to the caption when publishing. Include hashtags directly in the content field (platforms like Instagram only support hashtags as caption text). For YouTube keywords, use the tags field instead.","items":{"type":"string"}},"mentions":{"type":"array","items":{"type":"string"}},"crosspostingEnabled":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":true},"queuedFromProfile":{"type":"string","description":"Profile ID to schedule via queue."},"queueId":{"type":"string","description":"Specific queue ID to use when scheduling via queue."},"tiktokSettings":{"$ref":"#/components/schemas/TikTokPlatformData","description":"Root-level TikTok settings applied to the TikTok platforms sent in the same request. Merged into each platform's platformSpecificData, with platform-specific settings taking precedence. Returns 400 if sent without a platforms array."},"facebookSettings":{"$ref":"#/components/schemas/FacebookSettings","description":"Root-level Facebook settings applied to the Facebook platforms sent in the same request. Merged into each platform's platformSpecificData.facebookSettings, with platform-specific settings taking precedence. Returns 400 if sent without a platforms array."},"recycling":{"$ref":"#/components/schemas/RecyclingConfig"}},"additionalProperties":true},"example":{"content":"Updated content for our launch post!","scheduledFor":"2024-11-02T14:00:00Z"}}}},"responses":{"200":{"description":"Post updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostUpdateResponse"},"example":{"message":"Post updated successfully","post":{"_id":"65f1c0a9e2b5af0012ab34cd","content":"Updated content for our launch post!","status":"scheduled","scheduledFor":"2024-11-02T14:00:00Z"}}}}},"207":{"x-summary":"The post was updated, but some platforms failed to publish: check `post.status` and retry the failed platforms.","description":"The post was updated, but the inline publish that followed did not fully succeed.\n\n**207 is a 2xx status**, so `fetch(...).ok` is `true` and axios resolves. Branch on the status code explicitly.\n\nRead `post.status`: `partial` (some platforms published), `failed` (none published, terminal), or `scheduled` (transient errors, platforms reset to `pending`, Zernio retries automatically and this is not a failure). `platformResults` is omitted when the attempt aborted before producing per-platform results; `post.platforms[]` is always present.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostPublishIncompleteResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"x-summary":"The requested time collides with another queued post, or approval was requested on a non-draft post: change the time or the request.","description":"Conflict. One of:\n\n- `queue_slot_conflict`: the requested scheduledFor collides with another post already in that slot of the same queue. Choose a different time, omit scheduledFor to let the queue assign the next open slot, or send queueId: null to schedule outside the queue.\n- `invalid_resource_state`: requiresApproval was sent on a post that is not a draft.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}},"delete":{"x-resource-group":"publishing","operationId":"deletePost","tags":["Posts"],"summary":"Delete post","description":"Delete a post from Zernio. Upload quota is automatically refunded for draft and scheduled posts.\n\nAny status except `published` can be deleted:\n\n- `draft`\n- `scheduled`\n- `publishing`\n- `failed`\n- `partial`\n- `cancelled`\n\nPublished posts cannot be deleted; use the Unpublish endpoint instead.\n\n### Stopping pending entries\n\nDeleting a `publishing` or `partial` post is how you stop entries that are still pending, for example entries held on a disconnected account.\n\nIt removes the whole post record from Zernio, including the entries that were already published. It does not remove anything already live on a platform (use Unpublish for that first if needed).\n\nAn entry that a worker has already started sending when you delete may still go out. It may also fail, because media uploaded to Zernio and not used by another post is deleted with the post.\n\n### Side effects\n\n- Analytics for entries already published are removed too.\n- Deleting frees the content for re-creation, so the same caption and media are no longer reported as a duplicate.\n","parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostDeleteResponse"},"example":{"message":"Post deleted successfully"}}}},"400":{"description":"Cannot delete published posts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/posts/bulk-upload":{"post":{"x-resource-group":"publishing","operationId":"bulkUploadPosts","tags":["Posts"],"summary":"Bulk upload from CSV","description":"Create multiple posts by uploading a CSV file. Use dryRun=true to validate without creating posts.\n\n### Required columns\n\n- `platforms`, `profiles`, and a schedule: one of `schedule_time`, a `schedule_time_<platform>` override, `publish_now=true`, `use_queue=true`, or `is_draft=true`.\n- Content: at least one of `post_content`, `title`, or `media_urls`.\n\n### Aliases\n\nA handful of columns accept the JSON field name from POST /v1/posts, since integrators infer the CSV shape from that endpoint's body. When both are present the real CSV column wins, unless it is blank for that row, in which case the alias value is used.\n\n- `content` aliases `post_content`\n- `timezone` aliases `tz`\n- `scheduledFor` aliases `schedule_time`\n- `mediaUrls` aliases `media_urls`\n\n### Per-platform overrides\n\nThree dynamic column prefixes, one column per platform (e.g. `schedule_time_instagram`, `custom_content_tiktok`, `custom_media_youtube`):\n\n- `schedule_time_<platform>`\n- `custom_content_<platform>`\n- `custom_media_<platform>`\n\n### Other columns and warnings\n\n- Any other column is not read. It does not error, but it is reported in the response's `warnings` array as `unknown_columns:<a,b,c>` (see BulkUploadResult), so a misnamed or unsupported column is never silently dropped.\n- The `hashtags` and `mentions` columns are stored on the post but not added to the caption. Put them in `post_content` (or a `custom_content_<platform>` column). A filled column adds `not_added_to_caption:<columns>` to `warnings`.\n\n### Timezone\n\n`tz` sets the zone `schedule_time` is read in. A row without `tz` uses its profile's `timezone` (when all its target profiles share one), else UTC.\n\n### Row limits\n\n- 5000 rows is a hard cap that returns 400 above it.\n- 500 rows is only an advisory threshold: it adds `rows_exceed_advisory_limit:500` to `warnings` and the request still processes.\n\n### Example\n\nHeader + one data row:\n\n``` post_content,platforms,profiles,schedule_time,tz \"Hello world\",instagram,MyProfile,2026-09-01 10:00,America/New_York ```\n","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean","default":false}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"x-summary":"The bulk upload finished with every row succeeded or every row failed: check each entry in `results` for details.","description":"Bulk upload results. Returned when every row succeeded (or every row failed).\nA mix of successes and failures returns `207` instead, with the same body shape.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUploadResult"},"example":{"total":1,"valid":1,"invalid":0,"results":[{"rowIndex":1,"ok":true,"createdPostId":"69df8c12f102e11169c53cd3"}],"warnings":[]}}}},"207":{"x-summary":"Some rows were created and some failed: check each entry in `results` to see which rows failed and why, then resubmit them.","description":"Partial success: some rows were created and some failed. Body is identical in\nshape to the `200` response. Inspect each entry in `results` (`ok` plus `errors`)\nto see which rows failed and why.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUploadResult"},"example":{"total":1,"valid":0,"invalid":1,"results":[{"rowIndex":1,"ok":false,"errors":["unknown_profile:693ae023a552465131f3bdca1","no_account_for_platform:tiktok"]}],"warnings":[]}}}},"400":{"description":"Invalid CSV or validation errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"The account owner has a failed payment: update the payment method before uploading again.","description":"Payment required: the account owner has a failed payment. Not returned on dry-run.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Authenticated user not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"x-summary":"A rate limit was hit, either the API limit or an account cooldown for a CSV platform: wait and retry later.","description":"Rate limit exceeded. Possible causes: API rate limit (requests per minute) or account cooldown (one or more accounts for platforms specified in the CSV are temporarily rate-limited).\n","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}}}}}}},"/v1/posts/{postId}/retry":{"post":{"x-resource-group":"publishing","operationId":"retryPost","tags":["Posts"],"summary":"Retry failed post","description":"Immediately retries publishing a failed post. Returns the updated post with its new status.","parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Retry successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostRetryResponse"},"example":{"message":"Post published successfully","post":{"_id":"65f1c0a9e2b5af0012ab34cd","content":"Check out our new product!","status":"published","publishedAt":"2024-11-01T10:00:05Z","platforms":[{"platform":"twitter","accountId":{"_id":"64e1f0...","platform":"twitter","username":"@acme","displayName":"Acme Corp","isActive":true},"status":"published","platformPostId":"1234567890","platformPostUrl":"https://twitter.com/acme/status/1234567890"}]}}}}},"207":{"x-summary":"The retry ran but publishing did not fully succeed: check `post.status` and retry the failed platforms.","description":"The retry ran, but publishing did not fully succeed. Covers both a partial publish and a retry in which no platform published.\n\n**207 is a 2xx status**, so `fetch(...).ok` is `true` and axios resolves. Branch on the status code explicitly.\n\nThis response carries no `platformResults`. Read `post.status` (`partial`, `failed`, or `scheduled` when transient errors will be retried automatically) and `post.platforms[]` for per-platform detail.\n","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string","description":"Summary of why the retry did not fully succeed."},"post":{"$ref":"#/components/schemas/Post"}}}}}},"400":{"description":"Invalid state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Payment required: the account owner has a failed payment.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"403":{"x-summary":"A target account is ads-only or over the profile limit, or the post is inaccessible: connect the account for posting.","description":"Forbidden. Distinguish by the `code` field:\n\n- `ACCOUNT_NOT_ENABLED_FOR_POSTING`: a target account was connected for ads only (`enabled: false`) and cannot be posted to. Connect it as a posting account, then retry.\n- `PROFILE_OVER_LIMIT`: a target account belongs to a profile beyond the plan's profile limit.\n- `insufficient_permissions`: the post is not accessible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Post is currently publishing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"x-summary":"A rate limit was hit, such as the API limit or an account cooldown: wait and retry later.","description":"Rate limit exceeded. Possible causes: API rate limit (requests per minute) or account cooldown (temporarily rate-limited due to repeated errors).\n","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}}}}}}},"/v1/posts/{postId}/review":{"post":{"x-resource-group":"publishing","operationId":"reviewPost","tags":["Posts"],"summary":"Approve or reject a post","description":"Approves or rejects a post saved with `requiresApproval: true` (status `pending_approval`).\n`approve` schedules the post for its `scheduledFor` and fires the `post.scheduled` webhook. When that time has already passed, the post publishes within a couple of minutes.\n`reject` returns the post to `draft`.\nReturns 409 when the post is not `pending_approval`.\n","parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decision"],"properties":{"decision":{"type":"string","enum":["approve","reject"],"description":"approve schedules the post; reject returns it to draft."}}},"example":{"decision":"approve"}}}},"responses":{"200":{"description":"The reviewed post","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostGetResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The post is not pending_approval (code: invalid_resource_state), for example because it was already approved or rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/posts/{postId}/unpublish":{"post":{"x-resource-group":"publishing","operationId":"unpublishPost","tags":["Posts"],"summary":"Unpublish post","description":"Deletes a published post from the specified platform. The post record in Zernio is kept but its status is updated to cancelled.\nNot supported on Instagram, TikTok, or Snapchat. Threaded posts delete all items. YouTube deletion is permanent.\n","parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform"],"properties":{"platform":{"type":"string","description":"The platform to delete the post from","enum":["threads","facebook","twitter","linkedin","youtube","pinterest","reddit","bluesky","googlebusiness","telegram"]},"accountId":{"type":"string","description":"Which account's copy to delete when the post was published to several accounts on this platform. Required in that case."}}},"example":{"platform":"threads"}}}},"responses":{"200":{"description":"Post deleted from platform","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"example":{"success":true,"message":"Post deleted from threads successfully"}}}},"400":{"x-summary":"The post cannot be unpublished because the platform is unsupported or the post is unpublished, missing on that platform or lacks access.","description":"Invalid request: platform not supported for deletion, post not on that platform (or not for the given accountId), not published, no platform post ID, or no access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The post was published to several accounts on this platform and no accountId was sent (ambiguous_account).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Platform API deletion failed"}}}},"/v1/posts/{postId}/pin":{"post":{"x-resource-group":"publishing","operationId":"pinPost","tags":["Posts"],"summary":"Pin post","description":"Pins a published Facebook Page post to the top of its Page. Only Facebook posts can be pinned; any other platform answers 400 `platform_not_supported`. Works for posts on Pages connected through Facebook Login.\n","parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PinPostRequest"},"example":{"platform":"facebook"}}}},"responses":{"200":{"description":"Pin applied on Facebook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PinPostResponse"},"example":{"success":true,"pinned":true,"platformPostId":"123456789012345_987654321098765","message":"Post pinned to the top of the Facebook Page"}}}},"400":{"x-summary":"The pin request is invalid, like a post not on Facebook or not published, or Facebook rejected it: fix it and retry.","description":"Invalid request: invalid postId or accountId, the post or the chosen account is not on Facebook (`platform_not_supported`), the Facebook entry is not published or has no platform post ID, no access token, or Facebook rejected the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The post was published to several Facebook accounts and no accountId was sent (ambiguous_account).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Facebook API call failed"}}}},"/v1/posts/{postId}/unpin":{"post":{"x-resource-group":"publishing","operationId":"unpinPost","tags":["Posts"],"summary":"Unpin post","description":"Unpins a published Facebook Page post from the top of its Page. Only Facebook posts can be unpinned; any other platform answers 400 `platform_not_supported`.\n","parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PinPostRequest"},"example":{"platform":"facebook"}}}},"responses":{"200":{"description":"Unpin applied on Facebook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PinPostResponse"},"example":{"success":true,"pinned":false,"platformPostId":"123456789012345_987654321098765","message":"Post unpinned from the Facebook Page"}}}},"400":{"x-summary":"The pin request is invalid, like a post not on Facebook or not published, or Facebook rejected it: fix it and retry.","description":"Invalid request: invalid postId or accountId, the post or the chosen account is not on Facebook (`platform_not_supported`), the Facebook entry is not published or has no platform post ID, no access token, or Facebook rejected the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The post was published to several Facebook accounts and no accountId was sent (ambiguous_account).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Facebook API call failed"}}}},"/v1/posts/{postId}/edit":{"post":{"x-resource-group":"publishing","operationId":"editPost","tags":["Posts"],"summary":"Edit published post","description":"Edit the text of an already-published post. Supported on X, Discord, Facebook, Reddit, LinkedIn, Telegram, Pinterest, Google Business Profile, YouTube, and Slack.\n\nWhen a post was published to several accounts on the same platform, pass `accountId` to pick which account's copy to edit (without it the request returns 409). Each platform enforces its own rules.\n\n**X**\n\n- Connected X account must have an active X Premium subscription\n- Must be within 1 hour of original publish time\n- Maximum 5 edits per tweet (enforced by X)\n- Threads cannot be edited, only single tweets\n- X assigns a NEW post ID on edit, returned as `id`\n\n**Discord**\n\n- No time limit and no premium requirement\n- The message ID is unchanged after the edit\n\n**Facebook**\n\n- Graph only permits editing a post that the same app created. This works on posts published through Zernio and is rejected for posts created in Meta Business Suite / Composer or by another tool\n- Media cannot be swapped, only the message text\n- Reactions, comments, and shares are preserved. The post ID is unchanged\n\n**Reddit**\n\n- Self-posts only. A link post has no editable body and is rejected before the write\n- Body only. Reddit exposes no API to edit a post title, ever\n- The post ID is unchanged\n\n**LinkedIn**\n\n- Text only, no time limit. Media, polls, articles, and reshare targets cannot be changed\n- Works for member and organization posts published through this API. The post keeps its ID and LinkedIn shows an \"edited\" marker\n- Text is limited to 3,000 characters; mentions and hashtags are preserved\n\n**Telegram**\n\n- No time limit; messages published through Zernio are editable indefinitely\n- Text posts: edits the message text (up to 4096 characters)\n- Media posts: edits the caption only (up to 1024 characters). The media itself cannot be swapped\n- For albums, the caption shown on the album (its first message) is edited\n- The message ID is unchanged\n\n**Pinterest**\n\n- Description only, maximum 800 characters. Media, link, and board cannot be changed, and a pin title derived from the old content's first line at publish stays as-is\n- Pinterest's pin-update endpoint is currently in closed beta. Until the app is allowlisted by Pinterest, edits are rejected with a \"beta feature not yet enabled\" error\n- The pin ID is unchanged\n\n**Google Business Profile**\n\n- Post body (summary) text only. Call-to-action, event/offer fields, and media are untouched\n- No time limit and no edit limit. The post ID is unchanged\n- The post must still exist on Google: a post deleted from the Business Profile dashboard, or an event/offer post past its end date, returns a 404\n\n**YouTube**\n\n- `content` replaces the video description only. The title is unchanged, even if it was originally derived from the content's first line at publish time\n- Title, tags, thumbnail, and privacy edits belong to `POST /v1/posts/{postId}/update-metadata`\n- No time window and no edit cap. The video ID is unchanged\n\n**Slack**\n\n- Text only, up to 4,000 characters. Media cannot be swapped, and media posts whose share message reference never resolved cannot be edited\n- No time limit unless workspace admins restrict message editing\n- The message ID is unchanged\n\nMedia edits are not supported on any platform. The post record in Zernio is updated with the new content and an edit-history entry.\n","parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform","content"],"properties":{"platform":{"type":"string","description":"The platform to edit the post on.","enum":["twitter","discord","facebook","reddit","linkedin","telegram","pinterest","googlebusiness","youtube","slack"]},"content":{"type":"string","description":"The new post text content"},"accountId":{"type":"string","description":"Which account's copy of the post to edit when the post was published to several accounts on the same platform. Required in that case.\n"}}},"example":{"platform":"facebook","content":"Updated post text with corrected information"}}}},"responses":{"200":{"description":"Post edited successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string","description":"The platform post ID after the edit. X assigns a new ID; every other platform returns the original ID unchanged.\n"},"url":{"type":"string","format":"uri","description":"URL of the edited post"},"message":{"type":"string"}}},"example":{"success":true,"id":"1234567890123456790","url":"https://twitter.com/i/web/status/1234567890123456790","message":"twitter post edited successfully"}}}},"400":{"x-summary":"The edit is invalid or the platform rejected it, like an unpublished post, expired edit window or too-long content: fix the request.","description":"Invalid request: platform not supported, post not published, edit window expired, not X Premium, or missing content.\n\nAlso returned when the platform rejects the edit with a 4xx, including:\n\n- A Reddit link post (no editable body).\n- A Facebook post not created by this app.\n- Content over a platform's length limit (LinkedIn 3,000; Telegram 4096 text / 1024 caption; Pinterest 800; Slack 4,000).\n- A Telegram edit with unchanged content.\n- A Pinterest app not yet allowlisted for the pin-update beta.\n"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The post was published to several accounts on this platform and no accountId was sent (ambiguous_account).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Platform API edit failed for a reason the platform did not classify."}}}},"/v1/posts/{postId}/update-metadata":{"post":{"x-resource-group":"publishing","operationId":"updatePostMetadata","tags":["Posts"],"summary":"Update post metadata","description":"Updates metadata of a published video on the specified platform without re-uploading. Currently only supported for YouTube. At least one updatable field is required.\n\n### Two modes\n\n1. Post-based (video published through Zernio): pass the Zernio postId in the URL and platform in the body.\n2. Direct video ID (video uploaded outside Zernio, e.g. directly to YouTube): use _ as the postId, and pass videoId + accountId + platform in the body. The accountId is the Zernio account ID for the connected YouTube channel.\n","parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"},"description":"Zernio post ID, or \"_\" when using direct video ID mode"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform"],"properties":{"platform":{"type":"string","description":"The platform to update metadata on","enum":["youtube"]},"videoId":{"type":"string","description":"YouTube video ID (required for direct mode, ignored for post-based mode)"},"accountId":{"type":"string","description":"Zernio account ID. Required for direct mode. In post-based mode, picks which account's copy to update when the post was published to several accounts on this platform (required in that case)."},"title":{"type":"string","maxLength":100,"description":"New video title (max 100 characters for YouTube)"},"description":{"type":"string","description":"New video description"},"tags":{"type":"array","items":{"type":"string","maxLength":100},"description":"Array of keyword tags (max 500 characters combined for YouTube)"},"categoryId":{"type":"string","description":"YouTube video category ID"},"privacyStatus":{"type":"string","enum":["public","private","unlisted"],"description":"Video privacy setting"},"thumbnailUrl":{"type":"string","format":"uri","description":"Public URL of a custom thumbnail image (JPEG, PNG, or GIF, max 50 MB, recommended 1280x720). Works on any video you own, including videos not published through Zernio. The channel must be verified (phone verification) to set custom thumbnails.\n\n**Errors:**\n\n- 400 with the reason, no field updated: YouTube refuses the thumbnail (e.g. channel without the custom-thumbnail permission, video not owned by the connected channel), or the image URL cannot be fetched or has an unsupported format or size.\n- 429: YouTube thumbnail rate limit (uploadRateLimitExceeded). Retry later, not immediately, because retries keep the channel over its limit.\n- 500: any other temporary YouTube or network failure; can be retried.\n"},"madeForKids":{"type":"boolean","description":"COPPA compliance flag. Set true for child-directed content (restricts comments, notifications, ad targeting)."},"containsSyntheticMedia":{"type":"boolean","description":"AI-generated content disclosure. Set true if the video contains synthetic content that could be mistaken for real. YouTube may add a label."},"playlistId":{"type":"string","description":"YouTube playlist ID to add the video to (e.g. 'PLxxxxxxxxxxxxx'). Use GET /v1/accounts/{id}/youtube-playlists to list available playlists. Only playlists owned by the channel are supported."},"defaultLanguage":{"type":"string","description":"Language of the title and description (BCP-47, e.g. ko)."},"defaultAudioLanguage":{"type":"string","description":"Spoken language of the video (BCP-47, e.g. ko). When a video has no audio language, YouTube may set en-US once its metadata is updated."}}},"examples":{"post-based":{"summary":"Update a video published through Zernio","value":{"platform":"youtube","title":"Updated Video Title","description":"New SEO-optimized description","tags":["seo","marketing","tutorial"]}},"direct-video-id":{"summary":"Update a video uploaded directly to YouTube","value":{"platform":"youtube","videoId":"dQw4w9WgXcQ","accountId":"68fb37418bbca9c10cbfef26","title":"Updated Title with SEO Keywords","tags":["seo","youtube","optimization"]}},"update-thumbnail":{"summary":"Update thumbnail on an existing video","value":{"platform":"youtube","videoId":"dQw4w9WgXcQ","accountId":"68fb37418bbca9c10cbfef26","thumbnailUrl":"https://example.com/my-thumbnail.jpg"}}}}}},"responses":{"200":{"description":"Metadata updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"videoId":{"type":"string","description":"Only present in direct video ID mode"},"updatedFields":{"type":"array","items":{"type":"string"}}}},"example":{"success":true,"message":"YouTube video metadata updated successfully","updatedFields":["title","description","tags"]}}}},"400":{"description":"Invalid request: unsupported platform, post not published, missing fields, validation error, or the thumbnail could not be set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The post was published to several accounts on this platform and no accountId was sent (ambiguous_account).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"x-summary":"YouTube rate-limited the thumbnail upload for the channel: wait and retry later rather than immediately.","description":"YouTube rate-limited the thumbnail upload for the channel (uploadRateLimitExceeded). Retry later, not immediately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Platform API update failed"}}}},"/v1/users":{"get":{"x-resource-group":"accounts","operationId":"listUsers","tags":["Users"],"summary":"List users","description":"Returns all users in the team including roles and profile access. Also returns the currentUserId of the caller.","responses":{"200":{"description":"Users","content":{"application/json":{"schema":{"type":"object","properties":{"currentUserId":{"type":"string"},"users":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"},"isRoot":{"type":"boolean"},"profileAccess":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"lastLoginAt":{"type":"string","format":"date-time","description":"Last sign-in, stamped at most once an hour, so it is accurate to within an hour rather than to the exact session. Omitted for members with no recorded sign-in since the field shipped, which does not mean they never signed in."}}}}}},"example":{"currentUserId":"6507a1b2c3d4e5f6a7b8c9d0","users":[{"_id":"6507a1b2c3d4e5f6a7b8c9d0","name":"John Doe","email":"john@example.com","role":"owner","isRoot":true,"profileAccess":["all"],"createdAt":"2024-01-15T10:30:00Z","lastLoginAt":"2024-06-02T09:12:00Z"},{"_id":"6507a1b2c3d4e5f6a7b8c9d1","name":"Jane Smith","email":"jane@example.com","role":"member","isRoot":false,"profileAccess":["64f0a1b2c3d4e5f6a7b8c9d0","64f0a1b2c3d4e5f6a7b8c9d1"],"createdAt":"2024-03-20T14:45:00Z","lastLoginAt":"2024-05-28T16:03:00Z"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/users/{userId}":{"get":{"x-resource-group":"accounts","operationId":"getUser","tags":["Users"],"summary":"Get user","description":"Returns a single user's details by ID, including name, email, and role.","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"User","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"},"isRoot":{"type":"boolean"},"profileAccess":{"type":"array","items":{"type":"string"}}}}}},"example":{"user":{"_id":"6507a1b2c3d4e5f6a7b8c9d0","name":"John Doe","email":"john@example.com","role":"owner","isRoot":true,"profileAccess":["all"]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/profiles":{"get":{"x-resource-group":"accounts","operationId":"listProfiles","tags":["Profiles"],"summary":"List profiles","description":"Returns profiles sorted default-first, then by creation date. Filter with name or externalId (exact match) and paginate with limit/skip; without those params the full list is returned unchanged. Use includeOverLimit=true to include profiles that exceed the plan limit.","parameters":[{"name":"includeOverLimit","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"When true, includes over-limit profiles (marked with isOverLimit: true)."},{"name":"name","in":"query","required":false,"schema":{"type":"string"},"description":"Exact-match filter on the profile name. Useful to recover a profile id after an ambiguous create (timeout followed by a 409 on retry)."},{"name":"externalId","in":"query","required":false,"schema":{"type":"string"},"description":"Exact-match filter on the externalId you set on the profile, to find the profile of one of your tenants without storing its Zernio id. Team members can each own a profile with the same externalId, so the result is a list."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Page size. When limit or skip is present, the response includes total and skip (and echoes limit)."},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Number of profiles to skip, applied after sorting and filtering."}],"responses":{"200":{"description":"Profiles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilesListResponse"},"examples":{"example":{"value":{"profiles":[{"_id":"64f0...","name":"Personal Brand","color":"#ffeda0","isDefault":true}]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"x-resource-group":"accounts","operationId":"createProfile","tags":["Profiles"],"summary":"Create profile","description":"Creates a new profile with a name, optional description, and color.\n\n### Uniqueness\n\n- Names are unique per team: a duplicate returns a 409 whose details.existingProfileId carries the id of the existing profile.\n- Set externalId to your own tenant or client id to find the profile later without storing its Zernio id. A duplicate externalId returns the same kind of 409, with code profile_external_id_conflict.\n\n### Idempotency\n\nSend an Idempotency-Key header to make retries safe. A retried create with the same key and body replays the original 201 (same _id) instead of conflicting.\n","parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string","example":"#ffeda0"},"timezone":{"type":"string","example":"Europe/Istanbul","description":"IANA timezone new posts on this profile use when they name no `timezone`. Omit to keep UTC. An unknown name returns 400."},"externalId":{"type":"string","minLength":1,"maxLength":255,"example":"tenant_42","description":"Your own identifier for this profile, typically the id of the tenant or client it serves in your system (1 to 255 characters, trimmed). Unique among the profiles of the user who owns the profile: a duplicate returns 409 profile_external_id_conflict. Look a profile up by it with GET /v1/profiles?externalId=."}}},"example":{"name":"Marketing Team","description":"Profile for marketing campaigns","color":"#4CAF50","timezone":"Europe/Istanbul","externalId":"tenant_42"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileCreateResponse"},"example":{"message":"Profile created successfully","profile":{"_id":"64f0a1b2c3d4e5f6a7b8c9d0","userId":"6507a1b2c3d4e5f6a7b8c9d0","name":"Marketing Team","description":"Profile for marketing campaigns","color":"#4CAF50","externalId":"tenant_42","isDefault":false,"createdAt":"2024-11-01T10:00:00Z"}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"Profile limit exceeded"},"409":{"x-summary":"A profile with this name or external ID already exists, or the same idempotency key is still processing: use `details.existingProfileId`.","description":"A profile with this name (code: profile_name_conflict) or this externalId (code: profile_external_id_conflict) already exists; details.existingProfileId carries the id of the existing profile. Also returned while a request with the same Idempotency-Key is still processing."},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"}}}},"/v1/profiles/{profileId}":{"get":{"x-resource-group":"accounts","operationId":"getProfile","tags":["Profiles"],"summary":"Get profile","description":"Returns a single profile by ID, including its name, color, and default status.","parameters":[{"name":"profileId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileGetResponse"},"example":{"profile":{"_id":"64f0a1b2c3d4e5f6a7b8c9d0","userId":"6507a1b2c3d4e5f6a7b8c9d0","name":"Marketing Team","description":"Profile for marketing campaigns","color":"#4CAF50","isDefault":false,"createdAt":"2024-11-01T10:00:00Z"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"x-resource-group":"accounts","operationId":"updateProfile","tags":["Profiles"],"summary":"Update profile","description":"Updates a profile's name, description, color, default timezone, externalId, or default status.","parameters":[{"name":"profileId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"name":{"type":"string","minLength":1},"description":{"type":["string","null"],"description":"Set to null to clear the description."},"color":{"type":"string"},"timezone":{"type":["string","null"],"example":"Europe/Istanbul","description":"IANA timezone new posts on this profile use when they name no `timezone`. Set to null to go back to UTC. An unknown name returns 400."},"externalId":{"type":["string","null"],"minLength":1,"maxLength":255,"example":"tenant_42","description":"Your own identifier for this profile (1 to 255 characters, trimmed). Set to null to clear it. A value another profile of the same owner already holds returns 409 profile_external_id_conflict."},"isDefault":{"type":"boolean"}}},"example":{"name":"Marketing Team (Updated)","color":"#2196F3","isDefault":true}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileUpdateResponse"},"example":{"message":"Profile updated successfully","profile":{"_id":"64f0a1b2c3d4e5f6a7b8c9d0","userId":"6507a1b2c3d4e5f6a7b8c9d0","name":"Marketing Team (Updated)","description":"Profile for marketing campaigns","color":"#2196F3","isDefault":true,"createdAt":"2024-11-01T10:00:00Z"}}}}},"400":{"x-summary":"The request is invalid, for example an unknown timezone or a body with no updatable field: send at least one valid field.","description":"Invalid request, including an unknown timezone or a body that carries none of name, description, color, timezone, externalId or isDefault (code: missing_required_field)."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"A profile with this name (code: profile_name_conflict) or this externalId (code: profile_external_id_conflict) already exists."}}},"delete":{"x-resource-group":"accounts","operationId":"deleteProfile","tags":["Profiles"],"summary":"Delete profile","description":"Permanently deletes a profile. Active connected accounts block deletion (returns 400) - disconnect them first. Any remaining disconnected accounts and provisioned WhatsApp numbers are moved to another of your profiles (a new one is created only if needed), never deleted.","parameters":[{"name":"profileId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileDeleteResponse"},"example":{"message":"Profile deleted successfully"}}}},"400":{"description":"Profile has active connected accounts; disconnect them first"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/accounts":{"get":{"x-resource-group":"accounts","operationId":"listAccounts","tags":["Accounts"],"summary":"List accounts","description":"Returns connected accounts. Only includes accounts within the plan limit by default. Follower data requires analytics add-on.\n\n### Pagination\n\nServer-side pagination is optional. When omitted, returns all accounts (backward-compatible).\n\n- Cursor paging: send `limit` alone for the first page, then pass `pagination.nextCursor` back as `cursor` until it is null. Pages are ordered by account id, so accounts added or removed between calls never shift a page. Cannot be combined with `page`, `sort` or `perProfile`.\n- Offset paging: send `page` and `limit` together. Out-of-range page/limit values are rejected with 400 rather than silently clamped.\n","parameters":[{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Filter accounts by profile ID. Must be a valid ObjectId."},{"name":"platform","in":"query","schema":{"type":"string"},"description":"Filter accounts by platform (e.g. \"instagram\", \"twitter\")."},{"name":"status","in":"query","schema":{"type":"string","enum":["connected","disconnected"]},"description":"Filter accounts by connection status. `connected` returns healthy accounts; `disconnected` returns accounts that need reconnection (per the same reconnection check surfaced in the dashboard). Omit to return accounts in any status. When combined with page/limit, pagination totals reflect the filtered result set.\n"},{"name":"search","in":"query","schema":{"type":"string","minLength":1,"maxLength":100},"description":"Case-insensitive match on the account username, display name or platform user id. A 24-character hexadecimal value is read as an account id and matches only that exact account. Combine with page/limit to paginate the matches."},{"name":"category","in":"query","schema":{"type":"string","enum":["social","ads","communication","blogs","crm","analytics"]},"description":"Only accounts of this kind. ads = ad accounts (Meta, Google, LinkedIn, Pinterest, TikTok, X, OpenAI, Reddit, Microsoft), communication = WhatsApp, Telegram, Discord, Slack and iMessage, blogs = Shopify and WordPress, crm = HubSpot, analytics = Google Analytics, social = every other platform."},{"name":"sort","in":"query","schema":{"type":"string","enum":["account","platform","profile","status","connected"]},"description":"Sort an offset-paginated listing (page and limit) by account name, platform, profile name, status (accounts needing a reconnect first when ascending) or connection date. Ties keep the default order: platform, then newest first."},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"description":"Direction for `sort`."},{"name":"includeOverLimit","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"When true, includes accounts from over-limit profiles."},{"name":"excludeHidden","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"When true, leaves out accounts the dashboard does not show as connections:\n\n- posting accounts with `enabled: false` (ads accounts are always kept, whatever their `enabled` value);\n- the internal `sms` and `phone` accounts behind each phone number.\n\nApplied before pagination, so page totals and `statusCounts` count only the remaining accounts. Sandbox accounts added by `includeSandbox` are appended after this filter. Accepts `true` or `false` in any letter case; any other value returns 400.\n"},{"name":"platforms","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated platforms (up to 50) to list together, the several-platform form of `platform`. Applied before pagination."},{"name":"adAccountRows","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"When true, lists every ads account row, one per ad account. By default an API key or OAuth app sees each ads login once per profile and platform, as the single ads connection it had before rows per ad account: its oldest row.\n\nOnly changes the result once ads are connected as one row per ad account; until then the two shapes are the same. Applied before pagination. Accepts `true` or `false` in any letter case; any other value returns 400.\n"},{"name":"includeCreatorAccounts","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"When true, also lists the accounts creators connected to your creator campaigns. They sit on creator profiles, which `GET /v1/profiles` does not list, and are left out by default.\n\nAsking for one creator profile by `profileId` lists its accounts either way. Applied before pagination. Accepts `true` or `false` in any letter case; any other value returns 400.\n"},{"name":"includeSandbox","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"When true, appends the shared WhatsApp sandbox account and the iMessage sandbox account to the list when they are active, honouring `platform` but no other filter.\n\nIgnored on a paginated request (page, limit or cursor) and together with `perProfile`. Accepts `true` or `false` in any letter case; any other value returns 400.\n"},{"name":"includeStatusCounts","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"When true, the response carries `statusCounts`: how many accounts match every other\nfilter of the request (with `status` lifted) in total and how many of those need a\nreconnection. Accepts `true` or `false` in any letter case; any other value returns 400.\n"},{"name":"page","in":"query","schema":{"type":"integer","minimum":1},"description":"Page number (1-based) for offset paging. Requires limit; omit page, limit and cursor for all accounts.\n"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500},"description":"Page size. With page, an offset page; alone or with cursor, a cursor page.\n"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from a previous response's `pagination.nextCursor`; returns the next page of `limit` accounts (500 when limit is omitted). A cursor we cannot parse returns 400. Cannot be combined with page."},{"name":"profileIds","in":"query","schema":{"type":"string"},"description":"Comma-separated profile IDs (up to 50) to preview, together with perProfile. The response then also carries `profileTotals`."},{"name":"perProfile","in":"query","schema":{"type":"integer","minimum":1,"maximum":24},"description":"Return a preview of each profile in profileIds: the newest account of every platform it has, topped up to at least N. Requires profileIds; cannot be combined with page, limit or cursor."}],"responses":{"200":{"description":"Accounts (with optional pagination)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountsListResponse"},"examples":{"example":{"value":{"accounts":[{"_id":"64e1...","platform":"twitter","profileId":{"_id":"64f0...","name":"My Brand","slug":"my-brand"},"username":"@acme","displayName":"Acme","profileUrl":"https://x.com/acme","isActive":true}],"hasAnalyticsAccess":false}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/v1/accounts/follower-stats":{"get":{"x-resource-group":"analytics","operationId":"getFollowerStats","tags":["Accounts","Analytics"],"summary":"Get follower stats","description":"Returns follower count history and growth metrics for connected accounts.\nRequires analytics add-on subscription. Follower counts are refreshed once per day.\n","parameters":[{"name":"accountIds","in":"query","schema":{"type":"string"},"description":"Comma-separated list of account IDs (optional, defaults to all user's accounts)"},{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Filter by profile ID"},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Start date in YYYY-MM-DD format (defaults to 30 days ago)"},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"End date in YYYY-MM-DD format (defaults to today)"},{"name":"granularity","in":"query","schema":{"type":"string","enum":["daily","weekly","monthly"],"default":"daily"},"description":"Data aggregation level"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":25},"description":"Accounts per page, ordered by account id. Send it to page through accounts; the response then carries `pagination.nextCursor`. Without limit or cursor every matching account is returned."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from a previous response's `pagination.nextCursor`; returns the next page of `limit` accounts (25 when limit is omitted). A cursor we cannot parse returns 400."}],"responses":{"200":{"description":"Follower stats","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowerStatsResponse"},"examples":{"example":{"value":{"accounts":[{"_id":"64e1...","platform":"twitter","username":"@acme","currentFollowers":1250,"growth":50,"growthPercentage":4.17,"dataPoints":30}],"stats":{"64e1...":[{"date":"2024-01-01","followers":1200},{"date":"2024-01-02","followers":1250}]},"dateRange":{"from":"2024-01-01T00:00:00.000Z","to":"2024-01-31T23:59:59.999Z"},"granularity":"daily"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Analytics add-on required"},"message":{"type":"string","example":"Follower stats tracking requires the Analytics add-on. Please upgrade to access this feature."},"requiresAddon":{"type":"boolean","example":true}}}}}}}}},"/v1/accounts/{accountId}":{"put":{"x-resource-group":"accounts","operationId":"updateAccount","tags":["Accounts"],"summary":"Update account","description":"Updates a connected account's display name or username override.\n\n### X capabilities\n\nFor X accounts on usage-based billing, also accepts an `xCapabilities` object to toggle background API operations that incur X API pass-through costs.\n\n- Both fields are opt-in (default `false`).\n- When off, no analytics syncs or DM polling are performed for that account, and no API call is metered for those operations.\n- Publishing and deleting posts are always available regardless of these toggles.\n- Setting `xCapabilities` on a non-X account returns 400.\n\n### Meta ads sync\n\nFor Facebook accounts, also accepts `metaAdsSyncEnabled` to sync the Meta ads of the ad accounts the account reaches without a Meta Ads connection. See the field for what turning it on and off does.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string"},"displayName":{"type":"string"},"xCapabilities":{"type":"object","description":"X only. Per-account opt-in toggles for background API\noperations that incur X API pass-through costs. Each call is\nbilled at the X tier rate. Either field can be\nsent independently; omitted fields are unchanged.\n","properties":{"analytics":{"type":"boolean","description":"Enable periodic analytics reads (impressions, likes, etc.)\nfor this X account. Each X API call is metered as\n`posts_read` and billed pass-through (~$0.005/call at the\ntime of writing; the actual rate depends on X's pricing tier).\n"},"inbox":{"type":"boolean","description":"Enable DM polling and inbox sync for this X account. DM\nreads are metered as `dm_event_read` (~$0.010/call) and\nDM sends as `dm_interaction_create` (~$0.015/call), both\nbilled pass-through. DM sends fire only on user-initiated\nactions; reads/polling fire only when this flag is true.\n"}}},"metaAdsSyncEnabled":{"type":"boolean","description":"Facebook only (400 `invalid_field_value` on any other platform). Off by default for every Facebook account.\n\n`true` makes this account sync the Meta ads of the ad accounts it reaches, like a `metaads` connection.\n\n- The first sync starts at once (14 days, then 90 days of history in the background) and fires `account.ads.initial_sync_completed` for this `accountId` with `platform: metaads`.\n- It then refreshes on the Meta Ads schedule.\n- Each switch from `false` to `true` runs another initial sync and fires the webhook again. Sending `true` while it is on changes nothing.\n- Needs `ads_management` and `ads_read` on the account (403 `reconnect_required` otherwise, with `details.requiredPermissions`).\n- Needs ads access (403 `ads_addon_required`) and room in the managed ads allowance (403 `ads_allowance_exceeded`).\n- While a `metaads` connection has this account as `parentAccountId`, that connection syncs the ads instead.\n\nSynced active ads count on the managed ads meter like ads from a Meta Ads\nconnection.\n\n`false` stops the sync. Ads already synced are kept, never deleted: they\nstop updating and stop counting on the meter, and a `metaads` connection\nof yours that reaches the same ad account takes them over. Posting, inbox\nand comments on the account are not affected.\n"}}},"example":{"displayName":"Acme Corporation Official","xCapabilities":{"analytics":true,"inbox":false}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"username":{"type":"string"},"displayName":{"type":"string"},"xCapabilities":{"type":"object","description":"Echo of the resulting `xCapabilities` state, returned only\nwhen the request body included an `xCapabilities` object.\n","properties":{"analytics":{"type":"boolean"},"inbox":{"type":"boolean"}}},"metaAdsSyncEnabled":{"type":"boolean","description":"The resulting setting, returned only when the request body included `metaAdsSyncEnabled`."}}},"example":{"message":"Account updated successfully","username":"@acmecorp","displayName":"Acme Corporation Official","xCapabilities":{"analytics":true,"inbox":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`metaAdsSyncEnabled: true` on a Facebook account without `ads_management` and `ads_read` (`reconnect_required`), without the Ads add-on (`ads_addon_required`) or over the managed ads allowance (`ads_allowance_exceeded`)."},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"x-resource-group":"accounts","operationId":"moveAccountToProfile","tags":["Accounts"],"summary":"Move account to another profile","description":"Moves a connected account to a different profile owned by the same\nuser. The target profile must belong to the same user as the account.\n\nFor API keys restricted to specific profiles, BOTH the source account's\ncurrent profile AND the target profile must be in the key's allowed set.\nCalls with a target profile outside the key's scope return 403.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId"],"properties":{"profileId":{"type":"string","description":"Target profile ID (must be a valid ObjectId and owned by the same user as the account)."}}},"example":{"profileId":"65f1a2b3c4d5e6f7a8b9c0d1"}}}},"responses":{"200":{"description":"Account moved","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"profileId":{"type":"string"}}},"example":{"message":"Account updated successfully","profileId":"65f1a2b3c4d5e6f7a8b9c0d1"}}}},"400":{"description":"Missing or invalid profileId"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"API key does not have access to the source account or target profile"},"404":{"description":"Account or target profile not found"}}},"delete":{"x-resource-group":"accounts","operationId":"deleteAccount","tags":["Accounts"],"summary":"Disconnect account","description":"Disconnects and removes a connected account, and fires account.disconnected with disconnectionType intentional.\n\nThe account is kept for a 1h grace window. Reconnecting the same account within it restores it with the same accountId and its scheduled posts. After that it is deleted permanently.\n\nRepeating the call for an account already disconnected returns 404, the account stays in its 1h grace window and the disconnect is not re-run.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Disconnected","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}},"example":{"message":"Account disconnected successfully"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/accounts/health":{"get":{"x-resource-group":"accounts","operationId":"getAllAccountsHealth","tags":["Accounts"],"summary":"Check accounts health","description":"Returns health status of all connected accounts including token validity, permissions, and issues needing attention. A failing or stalled analytics sync (see `analyticsSync`) raises a healthy account to at least warning.","parameters":[{"name":"profileId","in":"query","description":"Filter by profile ID","schema":{"type":"string"}},{"name":"platform","in":"query","description":"Filter by platform","schema":{"type":"string","enum":["facebook","instagram","linkedin","twitter","tiktok","youtube","threads","pinterest","reddit","bluesky","googlebusiness","telegram","snapchat","discord","slack","whatsapp","shopify","wordpress","wix","linkedinads","metaads","pinterestads","tiktokads","xads","googleads","openaiads","redditads","microsoftads","whopads","hubspot","webflow","googleanalytics"]}},{"name":"status","in":"query","description":"Filter by health status","schema":{"type":"string","enum":["healthy","warning","error"]}}],"responses":{"200":{"description":"Account health summary","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of accounts"},"healthy":{"type":"integer","description":"Number of healthy accounts"},"warning":{"type":"integer","description":"Number of accounts with warnings"},"error":{"type":"integer","description":"Number of accounts with errors"},"needsReconnect":{"type":"integer","description":"Number of accounts needing reconnection"}}},"accounts":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string"},"username":{"type":"string"},"displayName":{"type":"string"},"profileId":{"type":"string"},"status":{"type":"string","enum":["healthy","warning","error"]},"canPost":{"type":"boolean"},"canFetchAnalytics":{"type":"boolean"},"tokenValid":{"type":"boolean"},"tokenExpiresAt":{"type":"string","format":"date-time"},"needsReconnect":{"type":"boolean","description":"True when the token is expired or revoked, permissions are missing, the account is inactive, or the platform rejected its stored credentials (the same flag the account listing reports as needsReconnection)."},"issues":{"type":"array","items":{"type":"string"}},"ownerUserId":{"type":"string","description":"User id of the profile owner, not necessarily the team member who connected the account."},"disconnectReason":{"type":["string","null"],"description":"Why the connection is broken or its token refresh is failing, from the most recent current cause. Null when the connection is healthy, including when the account is unhealthy for another reason (analytics, messaging restriction, missing analytics scopes), or when no cause is stored."},"disconnectionType":{"type":["string","null"],"enum":["intentional","unintentional",null],"description":"intentional: deliberately disconnected by the user or by Zernio (for example a plan downgrade), not a token failure. unintentional: token expired or revoked, or an auth failure. Null when disconnectReason is null."},"unhealthySince":{"type":["string","null"],"format":"date-time","description":"When the earliest current stored cause was recorded (the start of the outage); for an intentional disconnect, when it was disconnected. Null when the connection is healthy, including when the account is unhealthy for another reason (analytics, messaging restriction, missing analytics scopes), or when the time is unknown."},"analyticsSync":{"type":"object","description":"Absent on platforms without analytics sync. failing: several consecutive sync attempts failed. stalled: a sync was requested over 6 hours ago and never completed. never_synced: no sync has completed yet. Failing and stalled raise the account status to at least warning.","properties":{"status":{"type":"string","enum":["ok","failing","stalled","never_synced"]},"lastSyncedAt":{"type":["string","null"],"format":"date-time","description":"Last successful sync. Null when never synced or the latest attempt failed."}}},"inboundActivity":{"anyOf":[{"$ref":"#/components/schemas/InboundActivity"},{"type":"null"}],"description":"Present on WhatsApp, Instagram and Facebook accounts. An active WhatsApp number with no inbound message or comment 24 hours after its latest connect gets an entry in issues, which never changes status. Null for accounts connected before tracking shipped, until their first inbound event or next connect."},"messagingRestriction":{"type":["object","null"],"description":"Observed from Meta's own errors on our sends, not a live probe. It lags reality by one message in each direction.\n\n- Facebook/Instagram: error subcodes 2534122, 1893063, 2534029. Set on the first refused send, cleared when a later send succeeds.\n- WhatsApp: Cloud API error codes 131042 (payment or eligibility issue), 131031 (Business Account locked) and 368 (policy block). Set when a send or delivery status fails with one, cleared when a later message is delivered.\n\nAfter subcode 1893063 (Meta refusing the Page's messages), comment automation DMs are held and one is retried at `pausedUntil`: 30 minutes, doubling per refused retry up to 4 hours. Held DMs stay pending and are sent once Meta accepts again, within the 7-day private-reply window.\n","properties":{"code":{"type":["integer","null"],"description":"WhatsApp Cloud API error code. Null on Facebook and Instagram."},"subcode":{"type":["integer","null"],"description":"Meta error subcode (Facebook and Instagram). Null on WhatsApp."},"message":{"type":["string","null"]},"firstSeenAt":{"type":"string","format":"date-time"},"lastSeenAt":{"type":"string","format":"date-time"},"pausedUntil":{"type":["string","null"],"format":"date-time","description":"When held automation DMs are next retried. Null when nothing is held."}}}}}}}},"example":{"summary":{"total":5,"healthy":3,"warning":1,"error":1,"needsReconnect":1},"accounts":[{"accountId":"abc123","platform":"instagram","username":"myaccount","status":"healthy","canPost":true,"canFetchAnalytics":true,"tokenValid":true,"tokenExpiresAt":"2025-06-15T00:00:00Z","needsReconnect":false,"issues":[],"ownerUserId":"user_123","disconnectReason":null,"disconnectionType":null,"unhealthySince":null},{"accountId":"def456","platform":"twitter","username":"mytwitter","status":"error","canPost":false,"canFetchAnalytics":false,"tokenValid":false,"needsReconnect":true,"issues":["Token expired"],"ownerUserId":"user_123","disconnectReason":"Token expired","disconnectionType":"unintentional","unhealthySince":"2025-05-20T08:30:00Z"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/accounts/{accountId}/whatsapp/register":{"post":{"x-resource-group":"accounts","operationId":"registerWhatsAppNumber","tags":["WhatsApp"],"summary":"Register a connected WhatsApp number on the Cloud API","description":"Re-runs Meta's Cloud API registration for a WhatsApp account that is already connected.\n\nUse it when the number has its own two-step verification PIN. The connect flows register with a default PIN, and Meta rejects that with error 133005.\n\nThe number then fails every send with the misleading '(#200) You do not have the necessary permission to send messages' while the account still shows as connected.\n\nThe PIN is used for this call only and is not stored.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"The WhatsApp account ID"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"pin":{"type":"string","pattern":"^\\d{6}$","description":"The 6-digit two-step verification PIN set on the number. Omitting it applies Zernio's managed default registration PIN, the same one every Embedded Signup connect sets automatically."}}},"example":{"pin":"481902"}}}},"responses":{"200":{"description":"Number registered on the WhatsApp Cloud API","content":{"application/json":{"schema":{"type":"object","properties":{"registered":{"type":"boolean"},"accountId":{"type":"string"},"phoneNumberId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Invalid or expired credentials"},"404":{"description":"WhatsApp account not found"},"422":{"x-summary":"Meta rejected the registration, like a PIN mismatch, or the number cannot be registered through the API: check the PIN and number.","description":"Meta rejected the registration (e.g. PIN mismatch), or the number cannot be registered through the API."}}}},"/v1/accounts/{accountId}/whatsapp/request-code":{"post":{"x-resource-group":"accounts","operationId":"requestWhatsAppVerificationCode","tags":["WhatsApp"],"summary":"Request a Meta re-verification code for a BYO WhatsApp number","description":"Requests a new OTP from Meta for a bring-your-own WhatsApp number (its own WABA, migrated off another BSP) that Meta demoted to re-verification.\n\nThe code lands on the customer's own handset, so verifying it is necessarily self-service. Call POST /v1/accounts/{accountId}/whatsapp/verify-code with the code once it arrives.\n\nRate-limited to one request per 10 minutes per account, and Meta enforces its own cooldown on top of that.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"The WhatsApp account ID"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["SMS","VOICE"],"default":"SMS"},"language":{"type":"string","default":"en_US","description":"Meta locale code for the verification message, e.g. en_US."}}}}}},"responses":{"200":{"description":"Code requested, or the number was already CONNECTED with a current verification and no code was needed.","content":{"application/json":{"schema":{"type":"object","properties":{"requested":{"type":"boolean"},"alreadyActive":{"type":"boolean"},"method":{"type":"string"},"accountId":{"type":"string"},"phoneNumberId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"x-summary":"Meta already reports this number as verified: register the number instead of requesting a code.","description":"Meta already reports this number as VERIFIED. Call POST /v1/accounts/{accountId}/whatsapp/register instead."},"422":{"description":"The account has no phone number bound yet, it runs in coexistence with the WhatsApp Business app, or Meta rejected the code request."},"429":{"description":"Our own 10-minute-per-account cooldown is active, or Meta has escalated to a multi-hour lockout after repeated attempts.","headers":{"Retry-After":{"description":"Seconds remaining until the cooldown or lockout clears.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"x-summary":"Meta could not send a verification code for this number yet: retry shortly.","description":"Meta could not dispatch a code for this number yet. Retry shortly.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/accounts/{accountId}/whatsapp/verify-code":{"post":{"x-resource-group":"accounts","operationId":"verifyWhatsAppNumber","tags":["WhatsApp"],"summary":"Verify the Meta re-verification code for a BYO WhatsApp number","description":"Submits the OTP Meta sent in response to POST /v1/accounts/{accountId}/whatsapp/request-code.\nThis only verifies the number with Meta; it does not register it on the Cloud API.\nCall POST /v1/accounts/{accountId}/whatsapp/register afterward to complete activation.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"The WhatsApp account ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"The 6-digit code Meta sent to the phone. Non-digit separators (e.g. \"749-456\") are stripped automatically."}}},"example":{"code":"749456"}}}},"responses":{"200":{"description":"Number verified with Meta","content":{"application/json":{"schema":{"type":"object","properties":{"verified":{"type":"boolean"},"accountId":{"type":"string"},"phoneNumberId":{"type":"string"}}}}}},"400":{"description":"The code is malformed, or Meta rejected it as wrong or expired."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The account has no phone number bound to it yet."}}}},"/v1/accounts/{accountId}/health":{"get":{"x-resource-group":"accounts","operationId":"getAccountHealth","tags":["Accounts"],"summary":"Check account health","description":"Returns detailed health info for a specific account including token status, permissions, and recommendations.\n\nA failing or stalled analytics sync (see `analyticsSync`) raises a healthy account to at least `warning`.\n\n### Facebook, Instagram and Threads\n\nThe token is also probed live. A probe Meta refuses with a dead-token error sets `tokenStatus.valid` to `false` and names Meta's code, subcode and fbtrace in `issues`.\n\nThe exception: if an analytics sync succeeded with that token in the last six hours, the token stays `valid` and `issues` reports the probe as inconclusive, since Meta answers a transient 190 to live tokens now and then.\n\nNeither verdict disconnects the account. That happens only when a real operation fails, and `account.disconnected` is sent.\n\n### WhatsApp\n\nThe response also includes `platformConnection`, a live probe of the Meta link behind the channel (the same read as `GET /v1/whatsapp/number-info`).\n\nThe OAuth token can be perfectly valid while Meta refuses to serve the phone-number object (for example after a phone-side coexistence disconnect). So `tokenStatus` alone is not a liveness signal for WhatsApp.\n\n- When the Meta link is dead, `platformConnection.status` is `disconnected` and the overall `status` is `error`.\n- When Meta reports that the number's inbound message webhook does not reach Zernio, or subscribing the number's WhatsApp Business Account to Zernio's webhooks failed at connect, `platformConnection.inboundWebhookSubscribed` is `false`, an entry is added to `issues`, and the overall `status` is at least `warning`.\n- When `platformConnection.phoneStatus` is anything other than `CONNECTED`, an entry is added to `issues` and the overall `status` is at least `warning`; `BANNED` makes it `error`. `disconnectReason` stays null, since reconnecting does not lift a Meta status.\n\n### Standalone ads connections (`googleads`, `redditads`, `microsoftads`)\n\nA connection that cannot serve requests until a fresh OAuth repairs it adds an entry to `issues`. It also adds a recommendation to call `GET /v1/connect/{platform}/ads`, whose `authUrl` reconnects the same account.\n\nOn `redditads` this is a connection authorized before Zernio needed a Reddit permission it now uses (for example `adsconversions`). Reddit refuses those requests until the user reconnects and allows every permission on Reddit's consent screen.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"The account ID to check"}],"responses":{"200":{"description":"Account health details","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string"},"integrationLane":{"type":"string","enum":["business","developer"],"description":"TikTok only. The TikTok integration the account is connected through: business (TikTok for Business, Accounts API) or developer (the original integration). Absent on other platforms."},"sendCap":{"type":"object","description":"Google and Microsoft only: today's outbound mail allowance for the mailbox.","properties":{"limit":{"type":"integer"},"used":{"type":"integer"},"resetsAt":{"type":"string","format":"date-time"}}},"push":{"type":"string","enum":["active","pending","failed","not_applicable"],"description":"Google and Microsoft only: state of the provider change-notification subscriptions behind `message.received` and `calendar.event.*`. `pending` means a granted area has no live subscription yet (retried every 6 hours), `failed` that renewals keep failing (reconnect the account)."},"username":{"type":"string"},"displayName":{"type":"string"},"status":{"type":"string","enum":["healthy","warning","error"],"description":"Overall health status"},"tokenStatus":{"type":"object","properties":{"valid":{"type":"boolean","description":"Whether the token is valid"},"expiresAt":{"type":"string","format":"date-time"},"expiresIn":{"type":"string","description":"Human-readable time until expiry"},"needsRefresh":{"type":"boolean","description":"Whether token expires within 24 hours"}}},"permissions":{"type":"object","properties":{"posting":{"type":"array","items":{"type":"object","properties":{"scope":{"type":"string"},"granted":{"type":"boolean"},"required":{"type":"boolean"}}}},"analytics":{"type":"array","items":{"type":"object","properties":{"scope":{"type":"string"},"granted":{"type":"boolean"},"required":{"type":"boolean"}}}},"optional":{"type":"array","items":{"type":"object","properties":{"scope":{"type":"string"},"granted":{"type":"boolean"},"required":{"type":"boolean"}}}},"canPost":{"type":"boolean","description":"Whether the granted OAuth scopes allow posting. Scopes only: for WhatsApp, whether Meta lets the number send is `platformConnection.phoneStatus` and the overall `status`."},"canFetchAnalytics":{"type":"boolean"},"missingRequired":{"type":"array","items":{"type":"string"}}}},"issues":{"type":"array","items":{"type":"string"},"description":"List of issues found"},"recommendations":{"type":"array","items":{"type":"string"},"description":"Actionable recommendations to fix issues"},"ownerUserId":{"type":"string","description":"User id of the profile owner, not necessarily the team member who connected the account."},"disconnectReason":{"type":["string","null"],"description":"Why the connection is broken or its token refresh is failing, from the most recent current cause. Null when the connection is healthy, including when the account is unhealthy for another reason (analytics, messaging restriction, missing analytics scopes, Meta phone status), or when no cause is stored."},"disconnectionType":{"type":["string","null"],"enum":["intentional","unintentional",null],"description":"intentional: deliberately disconnected by the user or by Zernio (for example a plan downgrade), not a token failure. unintentional: token expired or revoked, or an auth failure. Null when disconnectReason is null."},"unhealthySince":{"type":["string","null"],"format":"date-time","description":"When the earliest current stored cause was recorded (the start of the outage); for an intentional disconnect, when it was disconnected. Null when the connection is healthy, including when the account is unhealthy for another reason (analytics, messaging restriction, missing analytics scopes, Meta phone status), or when unknown."},"analyticsSync":{"type":"object","description":"Absent on platforms without analytics sync. failing: several consecutive sync attempts failed. stalled: a sync was requested over 6 hours ago and never completed. never_synced: no sync has completed yet. Failing and stalled raise the account status to at least warning.","properties":{"status":{"type":"string","enum":["ok","failing","stalled","never_synced"]},"lastSyncedAt":{"type":["string","null"],"format":"date-time","description":"Last successful sync. Null when never synced or the latest attempt failed."}}},"inboundActivity":{"anyOf":[{"$ref":"#/components/schemas/InboundActivity"},{"type":"null"}],"description":"Present on WhatsApp, Instagram and Facebook accounts. An active WhatsApp number with no inbound message or comment 24 hours after its latest connect gets an entry in issues, which never changes status. Null for accounts connected before tracking shipped, until their first inbound event or next connect."},"messagingRestriction":{"type":["object","null"],"description":"Observed from Meta's own errors on our sends, not a live probe. It lags reality by one message in each direction.\n\n- **Facebook/Instagram:** error subcodes 2534122, 1893063, 2534029. Set on the first refused send, cleared when a later send succeeds.\n- **WhatsApp:** Cloud API error codes 131042 (payment or eligibility issue), 131031 (Business Account locked) and 368 (policy block). Set when a send or delivery status fails with one, cleared when a later message is delivered.\n\nAfter subcode 1893063 (Meta refusing the Page's messages), comment automation DMs are held and one is retried at `pausedUntil`: 30 minutes, doubling per refused retry up to 4 hours. Held DMs stay pending and are sent once Meta accepts again, within the 7-day private-reply window.\n","properties":{"code":{"type":["integer","null"],"description":"WhatsApp Cloud API error code. Null on Facebook and Instagram."},"subcode":{"type":["integer","null"],"description":"Meta error subcode (Facebook and Instagram). Null on WhatsApp."},"message":{"type":["string","null"]},"firstSeenAt":{"type":"string","format":"date-time"},"lastSeenAt":{"type":"string","format":"date-time"},"pausedUntil":{"type":["string","null"],"format":"date-time","description":"When held automation DMs are next retried. Null when nothing is held."}}},"platformConnection":{"type":"object","description":"WhatsApp accounts only. Live probe of the Meta link behind the channel, performed at request time (the same read as GET /v1/whatsapp/number-info).","properties":{"status":{"type":"string","enum":["connected","disconnected","unknown"],"description":"`connected` = Meta served the channel object. `disconnected` = Meta refused to serve it (Graph error 100, subcode 33), which is how a phone-side coexistence disconnect surfaces. `unknown` = the live read failed for another reason (timeout, transient Meta error), not evidence either way."},"checkedAt":{"type":"string","format":"date-time","description":"When this live probe ran (always the current request; never cached)"},"phoneStatus":{"type":["string","null"],"description":"Meta's own `status` field from the phone-number node (for example CONNECTED), when the object was readable. Anything other than CONNECTED adds an issue and raises `status` (BANNED: error, others: warning)."},"metaError":{"type":["object","null"],"description":"Set only when status is `disconnected`","properties":{"code":{"type":"integer","description":"Meta Graph error code (100)"},"subcode":{"type":"integer","description":"Meta Graph error subcode (33)"},"message":{"type":"string"}}},"inboundWebhookSubscribed":{"type":["boolean","null"],"description":"From the phone number's Meta health_status, overridden to `false` when subscribing the number's WhatsApp Business Account to Zernio's webhooks failed at connect.\n\n- `false`: Meta says Zernio is not subscribed to the message webhook for this number, or the subscribe failed when the number was connected, so inbound messages are not delivered, though the number is CONNECTED and can still send.\n- `false`, fix: re-subscribe (reconnect the number). If it stays `false`, the number is routed to a different WhatsApp Business Account (typically after linking it to a Facebook Page).\n- `true`: Meta reports no such problem.\n- `null`: Meta did not report it (read failed or no health_status); not evidence either way.\n"}}}}},"example":{"accountId":"abc123","platform":"instagram","username":"myaccount","displayName":"My Account","status":"healthy","tokenStatus":{"valid":true,"expiresAt":"2025-06-15T00:00:00Z","expiresIn":"180 days","needsRefresh":false},"permissions":{"posting":[{"scope":"instagram_basic","granted":true,"required":true},{"scope":"instagram_content_publish","granted":true,"required":true}],"analytics":[{"scope":"instagram_manage_insights","granted":true,"required":false}],"optional":[],"canPost":true,"canFetchAnalytics":true,"missingRequired":[]},"issues":[],"recommendations":[],"ownerUserId":"user_123","disconnectReason":null,"disconnectionType":null,"unhealthySince":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/accounts/{accountId}/posts":{"get":{"x-resource-group":"publishing","operationId":"getAccountPosts","tags":["Accounts"],"x-platforms":["facebook","instagram","twitter","bluesky","threads","youtube","linkedin","reddit","tiktok","pinterest"],"summary":"List posts published on the platform","description":"Returns the 25 most recent posts that exist on the platform for a connected account, read live from the platform API. This covers everything on the account, including posts that were never created through Zernio.\n\nUse it to obtain the platform's own post id, which the analytics endpoints take as input. On YouTube the returned `id` is the video ID that `GET /v1/analytics/youtube/daily-views`, `/video-retention` and `/demographics` expect as `videoId`, so this endpoint is what backs a video picker in your own UI.\n\n### Platform-specific fields\n\nNot every field applies to every platform. Absent fields are omitted from the response.\n\n- `reactionCount`: Facebook and LinkedIn.\n- `shareCount`: platform dependent.\n- `cid`: the Bluesky content id needed to reply.\n- `subreddit`: Reddit only.\n- `title`, `description`, `link`, `boardId` and `boardOwnerUsername`: Pinterest only (the native Pin values; `message` keeps title and description joined).\n\n### Expired tokens\n\nThe account's token is refreshed before the call when it has expired. When the refresh cannot recover it, the response is a 401 with code `TOKEN_EXPIRED` and the account has to be reconnected.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Posts list","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["success"]},"posts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The platform's own post id (the video ID on YouTube)"},"platform":{"type":"string"},"message":{"type":"string","description":"Caption or title, empty string when the post has no text"},"createdTime":{"type":"string","format":"date-time"},"permalink":{"type":"string","description":"Public URL of the post on the platform"},"picture":{"type":"string","description":"Thumbnail or media URL"},"mediaType":{"type":"string"},"commentCount":{"type":"integer"},"likeCount":{"type":"integer"},"reactionCount":{"type":"integer","description":"Facebook and LinkedIn only"},"shareCount":{"type":"integer"},"cid":{"type":"string","description":"Bluesky content id, required to reply to the post"},"subreddit":{"type":"string","description":"Reddit only"},"title":{"type":"string","description":"Pinterest only: native Pin title"},"description":{"type":"string","description":"Pinterest only: full native Pin description (Pinterest caps it at 800 characters)"},"link":{"type":"string","description":"Pinterest only: destination URL of the Pin, not the Pin page (see permalink)"},"boardId":{"type":"string","description":"Pinterest only: id of the board holding the Pin"},"boardOwnerUsername":{"type":"string","description":"Pinterest only: username of the board owner"}}}},"lastUpdated":{"type":"string","format":"date-time"}}},"example":{"status":"success","posts":[{"id":"dQw4w9WgXcQ","platform":"youtube","message":"How to schedule a post\n\nA short walkthrough.","createdTime":"2026-08-21T09:14:03.000Z","permalink":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","picture":"https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg","mediaType":"video","commentCount":12,"likeCount":340}],"lastUpdated":"2026-08-28T11:02:44.512Z"}}}},"400":{"description":"Invalid accountId, platform does not support posts listing, or the account has no access token"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"X analytics capability not enabled for this account (code X_ANALYTICS_NOT_ENABLED)"},"404":{"$ref":"#/components/responses/NotFound"},"502":{"$ref":"#/components/responses/UpstreamFailure"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/v1/accounts/{accountId}/follow-status/{userId}":{"get":{"x-resource-group":"accounts","operationId":"getInstagramFollowStatus","tags":["Accounts"],"x-platforms":["instagram"],"summary":"Check whether an Instagram user follows the account","description":"Resolves the follow relationship between an Instagram user and the connected account, plus their public profile counters.\n\n`userId` is the Instagram-scoped id (IGSID) Meta gives you on a webhook: `sender.id` on `message.received`, `comment.author.id` on `comment.received`.\n\n### When it cannot be resolved\n\n**Meta only answers for people who have MESSAGED the account.** Commenting grants no consent, so a commenter who has never DMed you is unresolvable. That is a platform rule, not a limitation of this endpoint.\n\nWhen it cannot be resolved the response is still `200` with `isFollower: null` and an `unavailableReason`, because \"unknown\" is a normal state to branch on:\n\n- `consent_required`: the user has never messaged this account.\n- `dm_access_disabled`: the account owner turned off Instagram Direct API access.\n- `not_messageable`: the id is not a messaging-scoped id.\n- `error`: a transient Graph API failure.\n\n### Gating comment automations\n\nTo gate a comment automation on this, use the automation's `audience` rules instead of calling this per comment. They run the same lookup only on comments that actually match a keyword, and can ask the commenter to confirm with one tap.\n\n### Caching\n\nAnswers are cached briefly per (account, user). Pass `refresh=true` right after asking someone to follow, so a follow from a moment ago is visible.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Instagram account ID"},{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"Instagram-scoped user id (IGSID) from a webhook payload"},{"name":"refresh","in":"query","required":false,"schema":{"type":"boolean"},"description":"Bypass the cache and re-query Meta"}],"responses":{"200":{"description":"Follow status (fields are null when Meta would not resolve it)","content":{"application/json":{"schema":{"type":"object","required":["userId","accountId","isFollower"],"properties":{"userId":{"type":"string"},"accountId":{"type":"string"},"isFollower":{"type":["boolean","null"],"description":"The user follows this account. Null = unknown, never \"no\"."},"isFollowedByAccount":{"type":["boolean","null"],"description":"This account follows the user."},"followerCount":{"type":["integer","null"]},"isVerified":{"type":["boolean","null"]},"username":{"type":["string","null"]},"name":{"type":["string","null"]},"unavailableReason":{"type":["string","null"],"enum":["consent_required","dm_access_disabled","not_messageable","error",null],"description":"Why the follow relationship could not be resolved. Null when it was."}}},"example":{"userId":"1312733120229708","accountId":"6977a34e77637c5c857c816c","isFollower":true,"isFollowedByAccount":false,"followerCount":25,"isVerified":false,"username":"to.bias8262","name":"Tobi Ma","unavailableReason":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/accounts/{accountId}/tiktok/commercial-music":{"get":{"x-resource-group":"accounts","operationId":"listTikTokCommercialMusic","tags":["Accounts"],"summary":"List trending commercial music","description":"Returns the 100 currently trending tracks of TikTok's Commercial Music Library for a TikTok account connected through the TikTok for Business app.\n\nThe list is not paged; countryCode selects the country chart.\n\n### Using a track in a post\n\nSend a track's clip.id as tiktokSettings.musicSoundInfo.musicSoundId when creating a post. Fall back to id only when the track has no clip.\n\nBoth publish, but with the full-track id TikTok has shown viewers \"This song is not available in your country\" on the sound page (observed from Germany, 2026-10-06). The clip id gave a working sound page for the same track.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"The TikTok account ID"},{"name":"countryCode","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2},"description":"Two-letter ISO 3166-1 country code of the chart to read (for example ES). Defaults to TikTok's global chart."}],"responses":{"200":{"description":"The trending tracks, rank 1 first","content":{"application/json":{"schema":{"type":"object","properties":{"tracks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The full track's song clip id. Accepted as musicSoundId, but prefer clip.id: posts published with this id have shown viewers a sound page saying the song is not available in their country (observed from Germany). TikTok rejects the commercial music id itself at publish time."},"commercialMusicId":{"type":"string","description":"TikTok's commercial_music_id, for reference only"},"name":{"type":"string"},"artist":{"type":"string"},"durationSec":{"type":"integer"},"genres":{"type":"array","items":{"type":"string"}},"previewUrl":{"type":"string","description":"Preview audio of the full track"},"thumbnailUrl":{"type":"string"},"rank":{"type":"integer","description":"Position in the trending chart, 1 first"},"clip":{"type":"object","description":"The trending excerpt of the track, when TikTok provides one. Send clip.id as musicSoundId: it publishes and its sound page opens for viewers, unlike the full-track id (observed from Germany, 2026-10-06).","properties":{"id":{"type":"string"},"durationSec":{"type":"integer"},"previewUrl":{"type":"string"}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Account not found"}}}},"/v1/accounts/{accountId}/tiktok/locations":{"get":{"x-resource-group":"accounts","operationId":"searchTikTokLocations","tags":["Accounts"],"summary":"Search TikTok location tags","description":"Searches the location tags a TikTok account connected through the TikTok for Business app can attach to a video post.\n\nSend a result's id and name as tiktokSettings.locationId and locationName when creating a post.\n\nTikTok answers the 20 closest matches and fills the list with fuzzy matches when nothing matches, so an unrelated result does not mean the place is missing.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"The TikTok account ID"},{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":100},"description":"Place name to search, for example a city, a venue or an address"}],"responses":{"200":{"description":"The closest location tags, best match first","content":{"application/json":{"schema":{"type":"object","properties":{"locations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The value to send as locationId"},"name":{"type":"string","description":"The value to send as locationName"},"address":{"type":"string","description":"Address or region TikTok shows for the place, for disambiguation"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Account not found"}}}},"/v1/accounts/{accountId}/tiktok/creator-info":{"get":{"x-resource-group":"accounts","operationId":"getTikTokCreatorInfo","tags":["Accounts"],"summary":"Get TikTok creator info","description":"Returns TikTok creator details, available privacy levels, posting limits, and commercial content options for a specific TikTok account. Only works with TikTok accounts.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"The TikTok account ID"},{"name":"mediaType","in":"query","required":false,"schema":{"type":"string","enum":["video","photo"],"default":"video"},"description":"The media type to get creator info for (affects available interaction settings)"}],"responses":{"200":{"description":"TikTok creator info and posting options","content":{"application/json":{"schema":{"type":"object","properties":{"creator":{"type":"object","properties":{"nickname":{"type":"string","description":"Creator display name"},"avatarUrl":{"type":"string","description":"Creator avatar URL"},"isVerified":{"type":"boolean","description":"Whether the creator is verified"},"canPostMore":{"type":"boolean","description":"Whether the creator can publish more posts right now"}}},"privacyLevels":{"type":"array","description":"Available privacy level options for this creator","items":{"type":"object","properties":{"value":{"type":"string","description":"Privacy level value to use when creating posts (e.g. PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY)"},"label":{"type":"string","description":"Human-readable label"}}}},"postingLimits":{"type":"object","properties":{"maxVideoDurationSec":{"type":"integer","description":"Maximum video duration in seconds"},"interactionSettings":{"type":"object","description":"Per-interaction descriptors for the comment, duet and stitch toggles. Each key matches the tiktokSettings field of the same name on the create-post request. allow_duet and allow_stitch are null when mediaType is photo, because TikTok does not apply duet or stitch to photo posts.","properties":{"allow_comment":{"type":"object","description":"Descriptor for the allow_comment toggle.","properties":{"enabled":{"type":"boolean","description":"Whether the creator permits this interaction. False means they disabled it in the TikTok app. This is availability, never the value the user selected."},"required":{"type":"boolean","description":"Whether tiktokSettings.allow_comment must be supplied when creating a post. Always true, because TikTok forbids defaulting it."},"default":{"type":"boolean","description":"Initial value a post composer should render. A UI seed only, never applied server-side when the field is omitted."},"label":{"type":"string","description":"Human-readable toggle label."}}},"allow_duet":{"type":["object","null"],"description":"Descriptor for the allow_duet toggle. Null when mediaType is photo.","properties":{"enabled":{"type":"boolean","description":"Whether the creator permits this interaction. False means they disabled it in the TikTok app. This is availability, never the value the user selected."},"required":{"type":"boolean","description":"Whether tiktokSettings.allow_duet must be supplied when creating a post. Always true, because TikTok forbids defaulting it."},"default":{"type":"boolean","description":"Initial value a post composer should render. A UI seed only, never applied server-side when the field is omitted."},"label":{"type":"string","description":"Human-readable toggle label."}}},"allow_stitch":{"type":["object","null"],"description":"Descriptor for the allow_stitch toggle. Null when mediaType is photo.","properties":{"enabled":{"type":"boolean","description":"Whether the creator permits this interaction. False means they disabled it in the TikTok app. This is availability, never the value the user selected."},"required":{"type":"boolean","description":"Whether tiktokSettings.allow_stitch must be supplied when creating a post. Always true, because TikTok forbids defaulting it."},"default":{"type":"boolean","description":"Initial value a post composer should render. A UI seed only, never applied server-side when the field is omitted."},"label":{"type":"string","description":"Human-readable toggle label."}}}}}}},"commercialContentTypes":{"type":"array","description":"Available commercial content disclosure options","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"requires":{"type":"array","items":{"type":"string"}}}}}}},"example":{"creator":{"nickname":"myaccount","avatarUrl":"https://example.com/avatar.jpg","isVerified":false,"canPostMore":true},"privacyLevels":[{"value":"PUBLIC_TO_EVERYONE","label":"Public To Everyone"},{"value":"MUTUAL_FOLLOW_FRIENDS","label":"Mutual Follow Friends"},{"value":"SELF_ONLY","label":"Self Only"}],"postingLimits":{"maxVideoDurationSec":600,"interactionSettings":{"allow_comment":{"enabled":true,"required":true,"default":false,"label":"Allow Comment"},"allow_duet":{"enabled":true,"required":true,"default":false,"label":"Allow Duet"},"allow_stitch":{"enabled":false,"required":true,"default":false,"label":"Allow Stitch"}}},"commercialContentTypes":[{"value":"none","label":"No Commercial Content"},{"value":"brand_organic","label":"Your Brand","requires":["is_brand_organic_post"]}]}}}},"400":{"description":"Account is not a TikTok account","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"This endpoint is only available for TikTok accounts"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Creator has reached TikTok daily posting limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"TikTok creator has reached the daily posting limit. Please try again later."}}}}}}},"/v1/auth/verify":{"get":{"x-resource-group":"public","operationId":"verifyCredential","tags":["API Keys"],"summary":"Verify credential","description":"Checks whether the bearer credential on this request is valid, without reading any data. Accepts an API key or an OAuth access token.\n\nIntended for clients that must validate a credential before use (for example an MCP server verifying an incoming token), so they do not have to call a data endpoint to do it.\n","responses":{"200":{"description":"Credential is valid","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"userId":{"type":"string"},"name":{"type":["string","null"],"description":"Display name of the credential's owner."},"email":{"type":["string","null"],"description":"Email of the credential's owner."},"authType":{"type":"string","enum":["api_key","oauth","session"]},"scope":{"type":["string","null"],"description":"Granted OAuth scopes, space-separated. Null for API keys."}}},"example":{"valid":true,"userId":"6507a1b2c3d4e5f6a7b8c9d0","name":"Ada Lovelace","email":"ada@example.com","authType":"oauth","scope":"posts:read posts:write accounts:read"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/feedback":{"post":{"x-resource-group":"accounts","operationId":"submitFeedback","tags":["Feedback"],"summary":"Submit feedback","description":"Report a bug, a missing feature or a documentation gap. Every submission\nis read by the Zernio team. Designed for AI agents: when a call fails in\na way that looks like our bug, or the API lacks something you need, send\none structured report here.\n\nInclude `endpoint` and `requestId` (the `x-request-id` response header of\nthe failing call) when you have them; they let us find the exact request.\n\nSubmitting the same `summary` again within 24 hours is idempotent: it\nreturns the original `id` with `duplicate: true` and a `200`. Each API\nuser can file at most 20 submissions per 24 hours.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","summary"],"properties":{"type":{"type":"string","enum":["bug","missing_feature","docs","other"],"description":"What kind of feedback this is."},"summary":{"type":"string","minLength":1,"maxLength":200,"description":"One line describing the problem or the missing capability. Also the dedup key."},"details":{"type":"string","maxLength":5000,"description":"Longer explanation: what you were trying to do, steps to reproduce, the use case."},"endpoint":{"type":"string","maxLength":300,"description":"The endpoint involved, e.g. `POST /v1/posts`."},"requestId":{"type":"string","maxLength":200,"description":"The `x-request-id` header of the failing response, if any."},"expected":{"type":"string","maxLength":2000,"description":"What you expected to happen."},"actual":{"type":"string","maxLength":2000,"description":"What actually happened, e.g. the error message."},"agent":{"type":"object","description":"Optional identification of the agent submitting the feedback.","properties":{"name":{"type":"string","maxLength":100,"description":"Agent or tool name, e.g. `claude-code`."},"model":{"type":"string","maxLength":100,"description":"Model powering the agent."}}}}},"example":{"type":"missing_feature","summary":"No way to set a TikTok post's cover frame timestamp","details":"I am scheduling TikTok videos and need to pick the cover frame. Nothing in platformSpecificData controls it.","endpoint":"POST /v1/posts","agent":{"name":"claude-code","model":"claude-opus-5-5"}}}}},"responses":{"200":{"x-summary":"This feedback duplicates one submitted in the last 24 hours, so the original submission's ID is returned.","description":"Duplicate of a submission made in the last 24 hours. Returns the original id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackReceipt"},"example":{"id":"66f7f0c2a1b2c3d4e5f60799","status":"received","duplicate":true}}}},"201":{"description":"Feedback received","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackReceipt"},"example":{"id":"66f7f0c2a1b2c3d4e5f60799","status":"received","duplicate":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"description":"More than 20 submissions in the last 24 hours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/api-keys":{"get":{"x-resource-group":"admin-plane","operationId":"listApiKeys","tags":["API Keys"],"summary":"List keys","description":"Returns API keys with a preview only, not the full key value. For a regular team member this is their own keys; for the team owner this is every team member's keys, each carrying a `createdBy` field.","responses":{"200":{"description":"API keys","content":{"application/json":{"schema":{"type":"object","properties":{"apiKeys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}},"example":{"apiKeys":[{"id":"6507a1b2c3d4e5f6a7b8c9d0","name":"Production API Key","keyPreview":"sk_12345678...abcdef01","expiresAt":"2025-12-31T23:59:59Z","createdAt":"2024-01-15T10:30:00Z","scope":"full","profileIds":[],"permission":"read-write","createdBy":{"id":"6507a1b2c3d4e5f6a7b8c9d0","email":"owner@example.com"}},{"id":"6507a1b2c3d4e5f6a7b8c9d1","name":"Analytics Read-Only","keyPreview":"sk_87654321...12345678","expiresAt":null,"createdAt":"2024-03-20T14:45:00Z","scope":"profiles","profileIds":[{"_id":"6507a1b2c3d4e5f6a7b8c9d0","name":"Main Brand","color":"#ffeda0"}],"permission":"read","createdBy":{"id":"6507a1b2c3d4e5f6a7b8c9d2","email":"member@example.com"}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"}}},"post":{"x-resource-group":"admin-plane","operationId":"createApiKey","tags":["API Keys"],"summary":"Create key","description":"Creates a new API key with an optional expiry. The full key value is only returned once in the response.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"expiresIn":{"type":"integer","description":"Days until expiry"},"scope":{"type":"string","enum":["full","profiles"],"description":"'full' grants access to all profiles (default), 'profiles' restricts to specific profiles","default":"full"},"profileIds":{"type":"array","items":{"type":"string"},"description":"Profile IDs this key can access. Required when scope is 'profiles'."},"permission":{"type":"string","enum":["read-write","read"],"description":"'read-write' allows all operations (default), '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","commerce","creator_campaigns","money","calendar","files"]},"description":"Resource groups to DISABLE on this key (opt-out denylist). Omit for a legacy full-access key.\n\nA key with any group disabled:\n\n- mints with the zrk_ prefix;\n- gets 403 with code=insufficient_permissions and required_group on operations in disabled groups (each operation's group is published as x-resource-group);\n- can never manage API keys, invites, or member identity.\n\nWith 'messages' disabled, the key cannot read or send direct messages through any API surface, and cannot create or edit a webhook subscription broader than itself. Existing subscriptions are governed by their own `disabledResourceGroups`, not this key's.\n\nOAuth connector tokens resolve against the same registry, but their groups are not settable yet.\n"}}},"example":{"name":"No Private Messages Key","disabledResourceGroups":["messages","contacts","webhooks"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"apiKey":{"$ref":"#/components/schemas/ApiKey"}}},"example":{"message":"API key created successfully","apiKey":{"id":"6507a1b2c3d4e5f6a7b8c9d0","name":"No Private Messages Key","keyPreview":"zrk_12345678...90abcdef","key":"zrk_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","expiresAt":null,"createdAt":"2024-01-15T10:30:00Z","scope":"full","profileIds":[],"permission":"read-write","disabledResourceGroups":["messages","contacts","webhooks"]}}}}},"400":{"description":"Invalid request (missing name, invalid scope/permission, or missing profileIds when scope is 'profiles')"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"}}}},"/v1/api-keys/{keyId}":{"delete":{"x-resource-group":"admin-plane","operationId":"deleteApiKey","tags":["API Keys"],"summary":"Delete key","description":"Permanently revokes and deletes an API key. The team owner can revoke any team member's key; a non-owner member can only revoke their own.","parameters":[{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}},"example":{"message":"API key deleted successfully"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/me/connected-apps":{"get":{"x-resource-group":"admin-plane","operationId":"listConnectedApps","tags":["Connected Apps"],"summary":"List connected apps","description":"Returns the OAuth clients (AI assistants and MCP connectors) the authenticated\nuser has authorized and that still hold a live token.\n\nRequires a session or a full-access API key. A profile-scoped API key, a\nrestricted (zrk_) API key, or an OAuth access token is rejected with 403: an\napp must not be able to enumerate its sibling authorizations, and connected-app\nmanagement is admin-plane.\n","responses":{"200":{"description":"Connected apps","content":{"application/json":{"schema":{"type":"object","properties":{"connectedApps":{"type":"array","items":{"$ref":"#/components/schemas/ConnectedApp"}}}},"example":{"connectedApps":[{"clientId":"late_cid_3f9c1a7b2d4e6f80a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718","clientName":"Claude","redirectHost":"claude.ai","scopes":["posts:read","posts:write","accounts:read"],"authorizedAt":"2026-07-02T09:14:00Z","lastUsedAt":"2026-07-30T18:02:11Z","tokenCount":2}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"}}}},"/v1/me/connected-apps/{clientId}":{"delete":{"x-resource-group":"admin-plane","operationId":"revokeConnectedApp","tags":["Connected Apps"],"summary":"Revoke connected app","description":"Ends an app's access: invalidates the client's pending authorization codes and\nrevokes every live token it holds for the authenticated user. Takes effect on\nthe app's next request.\n\nIdempotent while the authorization is still on record: revoking an app that\nwas already revoked returns 200 with `revokedTokens: 0`.\n\nRequires a session or a full-access API key. A profile-scoped API key, a\nrestricted (zrk_) API key, or an OAuth access token is rejected with 403.\n","parameters":[{"name":"clientId","in":"path","required":true,"description":"OAuth client id, as returned by GET /v1/me/connected-apps.","schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object","properties":{"revoked":{"type":"boolean"},"clientId":{"type":"string"},"revokedTokens":{"type":"integer","description":"Access and refresh tokens revoked by this call."},"invalidatedCodes":{"type":"integer","description":"Pending authorization codes invalidated by this call."}}},"example":{"revoked":true,"clientId":"late_cid_3f9c1a7b2d4e6f80a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718","revokedTokens":2,"invalidatedCodes":0}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"},"404":{"x-summary":"The authenticated user has never authorized this client, so there is nothing to revoke: check the client ID.","description":"The authenticated user has never authorized this client. Error code: oauth_client_not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/invite/tokens":{"post":{"x-resource-group":"admin-plane","operationId":"createInviteToken","tags":["Invites"],"summary":"Create invite token","description":"Generate a secure invite link to grant team members access to your profiles.\nInvites expire after 7 days and are single-use.\n\nReturns 403 when a requested profile is not found or not owned, or when\ncalled with a restricted (zrk_) API key: invite management is admin-plane.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["scope"],"properties":{"scope":{"type":"string","enum":["all","profiles"],"description":"'all' grants access to all profiles, 'profiles' restricts to specific profiles"},"profileIds":{"type":"array","items":{"type":"string"},"description":"Required if scope is 'profiles'. Array of profile IDs to grant access to."},"role":{"type":"string","enum":["admin","member","billing_admin","viewer"],"default":"member","description":"Org role granted to the invitee. Defaults to 'member'.\n\n- 'admin': manages the team (invite/remove members, change roles and access) and billing, but not ownership transfer or account deletion.\n- 'billing_admin' (displayed as Billing Manager): manages billing only.\n- 'viewer': a read-only member who can view everything in their profile scope but cannot perform any content mutation (publish, edit, delete, connect accounts).\n"},"disabledResourceGroups":{"type":"array","items":{"type":"string","enum":["publishing","engagement","messages","contacts","analytics","ads","telephony","accounts","billing","webhooks","commerce"]},"description":"Resource groups the invitee may not use once they join (the same groups as restricted API keys). Omitted or empty means full access.\n\nTheir dashboard hides those sections, and every API request into a disabled group, with any credential they hold, is refused with 403. Groups the caller lacks themselves are always added.\n"},"readOnly":{"type":"boolean","deprecated":true,"description":"Deprecated. Use role 'viewer' instead. When true, the invite is created with role 'viewer'. Cannot be combined with role 'billing_admin' or 'admin'."}}},"example":{"scope":"profiles","profileIds":["64f0a1b2c3d4e5f6a7b8c9d0","64f0a1b2c3d4e5f6a7b8c9d1"],"role":"member"}}}},"responses":{"201":{"description":"Invite token created","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"scope":{"type":"string"},"invitedProfileIds":{"type":"array","items":{"type":"string"}},"disabledResourceGroups":{"type":"array","items":{"type":"string"}},"expiresAt":{"type":"string","format":"date-time"},"inviteUrl":{"type":"string","format":"uri"}}},"example":{"token":"inv_abc123def456ghi789","scope":"profiles","invitedProfileIds":["64f0a1b2c3d4e5f6a7b8c9d0","64f0a1b2c3d4e5f6a7b8c9d1"],"disabledResourceGroups":[],"expiresAt":"2024-11-08T10:30:00Z","inviteUrl":"https://zernio.com/invite/inv_abc123def456ghi789"}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"}}}},"/v1/platform-invites":{"post":{"x-resource-group":"accounts","operationId":"createPlatformInvite","tags":["Connect"],"summary":"Create a connect link","description":"Create a single-use link that lets someone else connect their account to one of your profiles, without a Zernio login.\n\nFor Instagram, choose how they sign in with loginMethod. With facebook_login they sign in with Facebook and pick the Page linked to their Instagram account.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","platform"],"properties":{"profileId":{"type":"string","description":"The profile the account is connected to."},"platform":{"type":"string","enum":["facebook","instagram","linkedin","twitter","threads","tiktok","youtube","pinterest","reddit","bluesky","snapchat","googlebusiness"]},"accountId":{"type":"string","description":"Reconnect this existing account instead of adding a new one. It must belong to the profile and platform."},"loginMethod":{"type":"string","enum":["instagram_login","facebook_login"],"description":"Instagram only. instagram_login (the default) uses Instagram Login, facebook_login uses Facebook Login. A reconnect link keeps the method the account was connected with."},"expiresInDays":{"type":"integer","minimum":1,"maximum":30,"default":7,"description":"Days until the link expires."}}},"example":{"profileId":"64f0a1b2c3d4e5f6a7b8c9d0","platform":"instagram","loginMethod":"facebook_login","expiresInDays":14}}}},"responses":{"200":{"description":"Connect link created","content":{"application/json":{"schema":{"type":"object","properties":{"invite":{"type":"object","properties":{"_id":{"type":"string"},"platform":{"type":"string"},"loginMethod":{"type":["string","null"],"enum":["instagram_login","facebook_login",null]},"accountId":{"type":["string","null"]},"expiresAt":{"type":"string","format":"date-time"},"inviteUrl":{"type":"string","format":"uri"}}}}},"example":{"invite":{"_id":"64f0a1b2c3d4e5f6a7b8c9d2","platform":"instagram","loginMethod":"facebook_login","accountId":null,"expiresAt":"2026-11-17T10:30:00Z","inviteUrl":"https://zernio.com/api/v1/platform-invites/3f9a0c.../connect"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/connect/{platform}":{"get":{"x-resource-group":"accounts","operationId":"getConnectUrl","tags":["Connect"],"summary":"Get OAuth connect URL","description":"Initiate an OAuth connection flow. Returns an authUrl to redirect the user to.\n\n### Modes\n\n- Standard flow: Zernio hosts the selection UI, then redirects to your redirect_url.\n- Headless mode (headless=true): user is redirected to your redirect_url with OAuth data for custom UI. Use the platform-specific selection endpoints to complete.\n\n### Several accounts per platform\n\nA profile can hold several accounts of the same platform. Connecting a different account adds it as a new account, and reconnecting the SAME account keeps it and all of its history.\n\nAds connections stay one per profile.\n\nOn a legacy plan limited to N profiles, a new account is refused with 403 `platform_account_limit` once N accounts of its platform are connected.\n\n### TikTok\n\nEvery connection now goes through the TikTok for Business app.\n\nAn authorization that leaves out a permission the connected account needs changes nothing at all and comes back as `missing_tiktok_permissions`. Connect again and accept every permission on TikTok's screen.\n","parameters":[{"name":"platform","in":"path","required":true,"schema":{"type":"string","enum":["facebook","instagram","linkedin","twitter","tiktok","youtube","threads","reddit","pinterest","bluesky","googlebusiness","telegram","snapchat","discord","slack","whatsapp","google","microsoft"]},"description":"Social media platform to connect. `snapchat` is a closed beta with no public release date: it returns 403 `PLATFORM_BETA_RESTRICTED` until the account is approved."},{"name":"profileId","in":"query","required":true,"schema":{"type":"string"},"description":"Your Zernio profile ID (get from /v1/profiles). For WhatsApp, a Zernio-provisioned number can only be connected on the profile it was provisioned to; connecting from any other profile is rejected with a 409."},{"name":"reconnectAccountId","in":"query","schema":{"type":"string"},"description":"Refresh this existing account: a Zernio account id of the same platform on this profile (otherwise 400).\n\nThe OAuth callback and the selection endpoints (select-page, select-organization, select-board, select-location, Instagram and Snapchat selection) refuse with `reconnect_account_mismatch` a login that would write to a different account of the platform on this profile instead of this one.\n\nIn headless mode the marker travels in the redirect_url we hand you, so pass that URL back unchanged to the selection endpoint. On X it counts toward the OAuth state limit described under redirect_url.\n"},{"name":"oauthAppId","in":"query","schema":{"type":"string"},"description":"Connect through one of your own OAuth apps (see /v1/connect/oauth-apps), so the consent screen shows your app and the platform's limits are your app's. Without it the connect runs on Zernio's app, whatever apps the workspace has saved.\n\n- Only platforms listed in `platforms` of GET /v1/connect/oauth-apps accept an app. Any other returns 400, and so do ads connects (`adsConnect=true` in the redirect URL).\n- Connects that end on a destination picker also return 400, except Facebook Pages, Google Business locations, Pinterest boards and Snapchat public profiles (Instagram through Facebook Login, for example).\n- A LinkedIn connect through an app saves the member's own profile: organization pages, and mention lookups, stay on Zernio's app.\n- The connect requests the app's `scopeAreas`. `scopes` may narrow them but not add an area the app does not enable (400).\n- If the user does not grant every requested area, the account still connects and the redirect carries `missing_permissions=<areas>` (the headless POST returns `missingPermissions`).\n- If the platform refuses a permission your app is not approved for, the redirect carries `error=oauth_app_scope_not_allowed`.\n\nThe account remembers the app, and token refresh, publishing and inbox run on it. Reconnecting through another app, or without one, moves the account to that app.\n"},{"name":"expectedPlatformUserId","in":"query","schema":{"type":"string","maxLength":100},"description":"Only connect if the login lands on this platform account. Any other account ends the flow with `error=account_mismatch` (a 409 `account_mismatch` on POST /v1/connect/instagram/select-account) and nothing is written.\n\nCompared with every id the platform reports for the authorized account:\n\n- Any platform: the `platformUserId` of a Zernio account on this platform.\n- Instagram: either the app-scoped id or the professional account id (`metadata.instagramScopedId`, the `17841...` id that Facebook Login accounts hold as platformUserId).\n- TikTok: open_ids are app-scoped, so an id from your own TikTok app never matches. Use expectedUsername there.\n\nHonoured by the OAuth callback (every platform that connects without a selection step, Instagram Login included) and by the Instagram selection step. On the other selection endpoints you choose the destination yourself.\n\nIn headless mode the marker travels in the redirect_url we hand you, so pass that URL back unchanged. On X it counts toward the OAuth state limit described under redirect_url.\n"},{"name":"expectedUsername","in":"query","schema":{"type":"string","maxLength":100},"description":"Only connect if the authorized account's handle is this one (case-insensitive, a leading @ is ignored). Otherwise the flow ends with `error=account_mismatch` and `error_message` naming the handle that was authorized, and nothing is written.\n\nSame coverage and transport as expectedPlatformUserId; when both are sent, both must match. Use this on a first connection, where you hold the handle the user typed but no Zernio id yet.\n"},{"name":"forceReauth","in":"query","schema":{"type":"boolean","default":false},"description":"Instagram Login only (the default loginMethod); ignored elsewhere. Makes Instagram show its login page and ask for the credentials of the account to connect, even when another Instagram account is logged in on the device or app. Also hides the Facebook login option on that page.\n\nUse it when the person connecting manages several Instagram accounts on one phone: otherwise Instagram logs in, and converts to a professional account, whichever account is active, before any consent screen. Pair it with expectedUsername to also refuse a wrong account at the end.\n"},{"name":"redirect_url","in":"query","schema":{"type":"string","format":"uri"},"description":"Your custom redirect URL after the connection completes. It MUST be an absolute http(s) URL or a custom app scheme for mobile deeplinks (e.g. myapp://callback). A relative path is rejected with 400 `INVALID_REDIRECT_URL`.\n\n**Exit notice:** when `redirect_url` is an http(s) URL on another site (anything but zernio.com), every redirect of the flow lands first on `https://zernio.com/connect/continue?to=<your URL>`, a Zernio page that names your site and continues to it with one click. All params below reach your URL unchanged.\n\nA custom app scheme (myapp://...) never goes through the notice. In headless mode the redirects we hand you (and the `redirect_url` returned by the selection endpoints) are notice URLs: pass them back or navigate to them as they are.\n\n**X (twitter) length limit:** X caps the OAuth `state` at 500 characters and the redirect travels inside it (wrapped in the notice URL for an http(s) URL on another site). The URL-encoded form must be at most 258 characters for API callers, 310 for dashboard sessions.\n\nIn headless mode the appended `headless=true` counts toward that limit. A plain https URL on another site leaves about 165 to 190 characters of your own URL, depending on encoding. A longer one is rejected with 400 `INVALID_REDIRECT_URL`, and the error says by how much.\n\n**Success params** are appended with the URL API, so an existing query string is preserved:\n\n- Standard mode: connected={platform}&profileId=X&accountId=Y&username=Z.\n- Headless mode: OAuth data params for platforms requiring selection (e.g. LinkedIn orgs, Facebook pages). If no selection is needed, the account is created directly and the redirect includes accountId.\n\n**Failure params:** the browser goes to the same redirect_url with `error` and `platform` appended (always present). `error_message`, `is_user_fixable`, `reason`, `dashboard_url`, `missing_scopes`, `error_reason` and the `platform_error*` params are conditional: treat them as optional.\n\nYour own query params are kept on every redirect, but ours overwrite one of yours with the same name. On an error redirect we remove the internal `headless`, `adsConnect`, `adsScope`, `reconnectAccountId`, `expectedPlatformUserId` and `expectedUsername` markers added during the flow.\n\n**Correlation** params appear on every redirect from an OAuth callback (success and failure) and on the `redirect_url` returned by the selection endpoints such as POST /v1/connect/facebook/select-page:\n\n- `request_id`: the id we log that request under. Quote it when reporting a problem.\n- `stage`: where the flow ended. `authorize` = the platform's consent dialog returned an error or denial instead of a code. `callback` = we processed the returned code (success, a selection step, or a failure).\n- `stage` = `select_page`: the destination-selection endpoint (page, account, organization, board, location, profile or phone number) completed it.\n\n**Error details:**\n\n- `oauth_denied`: carries `error_message` and, when the platform sent them, its own `platform_error` (e.g. `access_denied`), `platform_error_reason` (e.g. `user_denied`) and `platform_error_description` (truncated to 500 characters). `is_user_fixable=true` when the platform reported that the user cancelled or declined.\n- `no_facebook_pages`: comes with `is_user_fixable=true`, an `error_message` telling the user to click \"Edit previous settings\" in Meta's dialog and tick the Page (or create one), and `error_reason` when Meta's token debug answered (values below).\n- `code_already_redeemed`: the same authorization code arrived more than once and an earlier request already processed it (the code is never sent to the platform twice). Not a failure: check GET /v1/accounts or wait for the `account.connected` webhook.\n- `missing_google_permissions` (YouTube, Google Business and Google Ads): the user unchecked permissions on Google's consent screen. Always with `is_user_fixable=true`. When Google reported granted scopes, `missing_scopes` lists the requested scopes not granted (comma-separated). Ask the user to connect again keeping every permission checked.\n- `no_youtube_channel`: Google authorized the account but it has no YouTube channel we can connect. Always with `is_user_fixable=true` and an `error_message`.\n\nUsual causes of `no_youtube_channel`: the user picked their personal Google identity instead of the Brand Account in Google's account chooser, they only have YouTube Studio access (not Brand Account owner or manager), or the account has no channel yet.\n\n`error_reason` values for `no_facebook_pages`:\n\n- `pages_permission_declined`: the user declined the pages_show_list permission.\n- `no_pages_granted`: the permission was granted with no Page ticked. Meta reports a user who manages no Page the same way, so this covers both.\n- `granted_pages_not_listed`: Pages were ticked but Meta listed none the user can manage, and a direct read of each ticked Page returned no access token.\n\n**Headless `userProfile`:** on headless Facebook success (`step=select_page`) and headless Instagram `facebook_login` success (`step=select_account`), `userProfile` is JSON percent-encoded once before being set as a query param, so it is encoded twice on the wire.\n\nAfter your framework decodes the query string once, run one more decodeURIComponent (or equivalent), then JSON.parse it. `tempToken` and `connect_token` are plain values.\n\n**Error values.** This list is NOT exhaustive and new values may be added at any time: treat an unrecognized value as a generic failure rather than matching exhaustively. Existing values are not renamed or removed without notice.\n\n- OAuth and callback: `oauth_denied`, `invalid_callback`, `invalid_state`, `unsupported_platform`, `connection_failed`, `internal_error`, `token_exchange_failed`, `byok_config_error`, `personal_account_not_supported`, `missing_google_permissions`, `missing_tiktok_permissions`, `platform_requires_destination`, `reconnect_account_mismatch`, `account_mismatch`, `instagram_login_method_mismatch`, `invalid_request`, `code_already_redeemed`.\n- Access and limits: `profile_not_found`, `invalid_profile_id`, `access_denied`, `account_limit_exceeded`, `profile_limit_exceeded`, `payment_required`.\n- Destination selection: `no_facebook_pages`, `facebook_pages_error`, `no_google_locations`, `google_locations_error`, `google_permission_denied`, `no_snapchat_public_profiles`, `snapchat_profiles_error`, `no_youtube_channel`, `discord_no_guild`, `slack_no_team`.\n- WhatsApp: `whatsapp_error`, `one_whatsapp_per_profile`, `whatsapp_number_already_connected`, `whatsapp_number_pinned_to_profile`, `whatsapp_coexistence_not_registered`, `connection_cancelled`.\n- Google Ads (platform=googleads): `google_ads_auth_failed`, `google_ads_invalid_state`, `google_ads_config_error`, `google_ads_token_failed`, `google_ads_quota_exhausted`, `google_ads_callback_error`.\n- TikTok Ads (platform=tiktokads): `tiktok_ads_auth_failed`, `tiktok_ads_invalid_state`, `tiktok_ads_access_denied`, `tiktok_ads_config_error`, `tiktok_ads_token_failed`, `tiktok_ads_account_not_found`, `tiktok_ads_callback_error`.\n- X Ads (platform=xads): `x_ads_denied`, `x_ads_auth_failed`, `x_ads_config_error`, `x_ads_account_not_found`, `x_ads_state_error`, `x_ads_token_failed`, `x_ads_token_missing`, `x_ads_callback_error`.\n- Reddit Ads (platform=redditads): `reddit_ads_auth_failed`, `reddit_ads_invalid_state`, `reddit_ads_access_denied`, `reddit_ads_scope_not_granted`, `reddit_ads_no_ad_accounts`, `reddit_ads_callback_error`.\n- Microsoft Ads (platform=microsoftads): `microsoft_ads_auth_failed`, `microsoft_ads_invalid_state`, `microsoft_ads_access_denied`, `microsoft_ads_scope_not_granted`, `microsoft_ads_unknown_user`, `microsoft_ads_no_ad_accounts`, `microsoft_ads_callback_error`.\n- Shopify (platform=shopify): `shopify_auth_failed`, `shopify_config_error`, `shopify_invalid_state`, `shopify_invalid_hmac`, `shopify_invalid_shop`, `shopify_missing_scopes`, `shopify_callback_error`.\n\nNotes:\n\n1. On this endpoint every upstream OAuth error collapses into `oauth_denied`, with the provider's values in the `platform_error*` params. The dedicated ads flows differ: they use their own denial slugs, and `google_ads_auth_failed` and `tiktok_ads_auth_failed` may carry the provider's raw error string in `error_message`.\n2. On the tiktok and twitter ads flows `platform` carries the ads platform id (`tiktokads`, `xads`), not the value in the request path. The googleads, redditads, microsoftads and shopify flows report `googleads`, `redditads`, `microsoftads` and `shopify`.\n3. `missing_tiktok_permissions`: the TikTok authorization left out a permission the already-connected account needs, so nothing changed and it keeps working as before. User-fixable: connect again and accept every permission on TikTok's screen.\n4. `instagram_login_method_mismatch`: an Instagram Login authorization landed on a profile whose Instagram account is connected through Facebook Login, so nothing changed. To refresh it, connect again with `loginMethod=facebook_login`. To move it to Instagram Login, disconnect it first.\n"},{"name":"scopes","in":"query","schema":{"type":"string","example":"posting,analytics","description":"Comma-separated subset of posting, analytics, comments, messaging, ads, email, calendar, files, contacts."},"description":"Comma-separated permission areas to request instead of the platform's full permission set.\n\n**Values:** `posting`, `analytics`, `comments`, `messaging`, `ads`; on google and microsoft, `email`, `calendar`, `files`, `contacts`.\n\n**Default:** omit it (what the dashboard does) to request everything the platform supports. Google and microsoft REQUIRE it (400 `INVALID_FIELD_VALUE` when absent) because their consent screens are reviewed per area.\n\nWhen present, the consent dialog asks only for the scopes behind those areas, plus the scopes every connection needs (identity, token refresh, listing the pages, organizations or channels the user picks from).\n\n- Scopes never asked for are absent from the account's `permissions`, and the health endpoints report them as not granted. A `posting`-only account cannot read analytics or the inbox until reconnected with more areas.\n- First comments need `comments`: a `posting`-only account publishes the post and skips the first comment.\n- Scopes in none of the areas (X likes, bookmarks and follows, Pinterest ads-only extras) are requested only when the parameter is omitted.\n\n**Supported on** facebook, instagram (both login methods), linkedin, twitter, tiktok, youtube, threads, reddit, pinterest, googlebusiness and slack (via `GET /v1/connect/slack`).\n\n**Rejected** with 400 `INVALID_FIELD_VALUE` (`param: scopes`) on bluesky, telegram, discord, snapchat and whatsapp (their dialog cannot be reduced), and for an empty list or an unknown area.\n\nWhat each area asks for, per platform (Google scopes shortened to their last path segment):\n\n| Platform | `posting` | `analytics` | `comments` | `messaging` | `ads` | Always requested |\n|---|---|---|---|---|---|---|\n| facebook | `pages_manage_posts` | `read_insights`, `pages_read_user_content` | `pages_manage_engagement`, `pages_read_user_content` | `pages_messaging` | `ads_management`, `ads_read`, `leads_retrieval`, `pages_manage_ads`, `instagram_basic`, `business_management` | `pages_show_list`, `pages_read_engagement`, `pages_manage_metadata` |\n| instagram (Instagram Login) | `instagram_business_content_publish` | `instagram_business_manage_insights` | `instagram_business_manage_comments` | `instagram_business_manage_messages` | none | `instagram_business_basic` |\n| instagram (`loginMethod=facebook_login`) | `instagram_content_publish` | `instagram_manage_insights` | `instagram_manage_comments` | `instagram_manage_messages` | `ads_management`, `ads_read`, `leads_retrieval`, `pages_manage_ads` | `instagram_basic`, `pages_show_list`, `pages_read_engagement`, `business_management`, `pages_messaging`, `pages_manage_metadata` |\n| linkedin | `w_member_social`, `w_organization_social`, `r_organization_social`, `r_organization_followers` | `r_member_postAnalytics`, `r_member_profileAnalytics`, `rw_organization_admin`, `r_organization_social`, `r_organization_followers` | `w_member_social`, `w_member_social_feed`, `w_organization_social`, `w_organization_social_feed`, `r_organization_social`, `r_organization_social_feed` | none | `r_ads`, `rw_ads`, `r_ads_reporting`, `r_marketing_leadgen_automation`, `rw_conversions` | `openid`, `profile`, `email`, `r_basicprofile`, `rw_organization_admin` |\n| twitter | `tweet.write`, `media.write` | (in the always-requested set) | `tweet.write`, `like.write`, `tweet.moderate.write` | `dm.read`, `dm.write`, `media.write` | none | `tweet.read`, `users.read`, `offline.access` |\n| tiktok | `video.publish` | `user.info.stats`, `user.insights`, `video.list`, `video.insights` | `comment.list`, `comment.list.manage`, `video.list` | `message.list.read`, `message.list.send`, `message.list.manage` | none | `user.info.basic`, `user.info.username`, `user.info.profile`, `user.account.type`, `video.publish`, `video.upload`, `video.list` |\n| youtube | `youtube.upload` | `yt-analytics.readonly` | `youtube.force-ssl` | none | none | `youtube` |\n| threads | `threads_content_publish`, `threads_manage_replies`, `threads_delete` | `threads_manage_insights` | `threads_content_publish`, `threads_read_replies`, `threads_manage_replies`, `threads_delete` | none | none | `threads_basic` |\n| reddit | `submit`, `read`, `mysubreddits`, `flair`, `history`, `edit` | `read`, `history` | `read`, `history`, `edit`, `vote` | `privatemessages` | none | `identity` |\n| pinterest | `boards:write`, `pins:read`, `pins:write` | `pins:read`, `user_accounts:read` | none | none | `ads:read`, `ads:write`, `boards:write`, `pins:read`, `pins:write` | `boards:read`, `user_accounts:read` |\n| googlebusiness | `business.manage` | `business.manage` | `business.manage` | none | none | `business.manage`, `userinfo.profile`, `userinfo.email` |\n| slack | `chat:write`, `chat:write.public`, `chat:write.customize`, `files:write`, `files:read` | none | none | `chat:write`, `chat:write.customize`, `files:write`, `files:read`, `channels:history`, `groups:history`, `im:history`, `mpim:history`, `im:read`, `im:write`, `mpim:read`, `users:read`, `reactions:read`, `reactions:write` | none | `channels:join`, `channels:read`, `groups:read`, `team:read` |\n\nGoogle and Microsoft accounts use the mailbox areas instead (`scopes` is required there):\n\n| Platform | `email` | `calendar` | `files` | `contacts` | Always requested |\n|---|---|---|---|---|---|\n| google | `gmail.modify` | `calendar` | `drive.file` (only files Zernio created or the user picked, see the Files tag) | `contacts.readonly` | `openid`, `userinfo.email`, `userinfo.profile` |\n| microsoft | `Mail.ReadWrite`, `Mail.Send` | `Calendars.ReadWrite` | `Files.ReadWrite` | `Contacts.Read` | `openid`, `profile`, `email`, `offline_access`, `User.Read` |\n\nAreas accumulate: reconnecting with more areas widens the grant, and `GET /v1/accounts/{accountId}/health` reports the result.\n"},{"name":"loginHint","in":"query","schema":{"type":"string","format":"email"},"description":"google and microsoft only: pre-fills the account picker with this address so the user lands on the right mailbox."},{"name":"headless","in":"query","schema":{"type":"boolean","default":false},"description":"When true, the user is redirected to your redirect_url with raw OAuth data (code, state) instead of Zernio's default account selection UI. Use this to build a custom connect experience."},{"name":"loginMethod","in":"query","schema":{"type":"string","enum":["instagram_login","facebook_login"],"default":"instagram_login"},"description":"Instagram only: which of the two Instagram connection methods to use. Ignored for every other platform.\n\n- `instagram_login` (default when omitted): the Instagram Login dialog. The user authorizes their Instagram professional account directly, no Facebook Page required. Exception: if omitted and `reconnectAccountId` names an account connected with `facebook_login`, the reconnect keeps that method.\n- `facebook_login`: the Facebook Login dialog (\"Instagram API with Facebook Login\"). The user authorizes a Facebook Page with a linked Instagram professional account, and every API call for that account runs through the Page. Use it when the customer manages Instagram through a Page and expects the Facebook consent screen.\n\nWith `facebook_login` the user picks a Page, so the callback continues at the account-selection step, `/v1/connect/instagram/select-account`. The default `instagram_login` has no selection step and connects directly.\n\n`facebook_login` supports `headless=true` like the other selection platforms. The callback redirects to your `redirect_url` with `profileId`, `tempToken`, `platform=instagram`, `step=select_account`, `userProfile` and `connect_token`.\n\n`userProfile` is the Facebook user's profile, same shape and encoding as the Facebook `step=select_page` redirect. Pass `profileId`, `tempToken` and `connect_token` into the select-account endpoints to finish.\n"},{"name":"onboarding","in":"query","schema":{"type":"string","enum":["api","business_app"]},"description":"WhatsApp only. Ignored for every other platform. Controls which screen Meta's Embedded Signup popup shows.\n\nIf omitted, the connection defaults to coexistence (same as `business_app` below), preserving existing behavior for numbers already on the WhatsApp Business app.\n\n`api`: standard Embedded Signup, showing Meta's WABA/number picker. Use this to connect a phone number already on Cloud API elsewhere.\n\n`business_app`: coexistence, i.e. 'Connect existing WhatsApp Business app' (a number shared between Cloud API and the consumer WhatsApp Business app).\n"},{"name":"signup","in":"query","schema":{"type":"string","enum":["hosted"]},"description":"WhatsApp only. Rejected with 400 `INVALID_FIELD_VALUE` on any other platform.\n\n`hosted`: `authUrl` points at a Zernio-hosted page on zernio.com instead of Meta's OAuth dialog, and the response carries `authUrl` only (no `state`). That page opens Meta's Embedded Signup popup itself, so it connects exactly the WhatsApp Business Account and number the user picked in the popup.\n\n**When to use it**: your users' Facebook logins manage several WhatsApp accounts. On the default redirect flow Meta only returns an authorization code, so when that login can see more than one number the user lands on Zernio's number picker and has to choose again.\n\n**Flow**: nothing to embed and no domain setup. Send the user to `authUrl`; they come back to `redirect_url` with the same params as the redirect flow.\n\n- Success: `connected=whatsapp`, `profileId`, `accountId`, `username` (plus `connect_token` for API-key callers).\n- Failure: `error` and `platform=whatsapp`, with the same values and extras as the redirect flow (see below), plus two of its own.\n\nRedirect-flow failures: `one_whatsapp_per_profile`, `whatsapp_number_already_connected`, `whatsapp_number_pinned_to_profile` and `whatsapp_coexistence_not_registered` with `is_user_fixable=true`; `payment_required` with `reason` and `dashboard_url`; `whatsapp_error` with `error_message` when Meta reported one.\n\nHosted-only failures:\n\n- `connection_cancelled`: the popup was closed before finishing (`error_message` carries Meta's last reported step or error when there is one).\n- `session_expired`: the user took longer than the 60 minute window the hosted page is valid for. Restart the flow with a new call.\n\n**Same as the redirect flow**: `onboarding` is carried through, and a pre-verified Zernio-provisioned number is attached.\n\nWhen a previously disconnected account for this profile can simply be re-enabled, this endpoint re-enables it and returns the account directly instead of a URL. `headless` has no effect, because there is no selection step left to hand you.\n\n**The page** shows the same guidance as the Zernio dashboard: a pre-verified Zernio-provisioned number is called out by name (\"choose it in Meta's list, no code will be asked\").\n\nCoexistence and standard signups get their explainer video, and a step-by-step checklist stays visible while Meta's popup is open. Skin it with `brandName`, `primaryColor` and `language` below.\n"},{"name":"brandName","in":"query","schema":{"type":"string","minLength":1,"maxLength":60},"description":"Your product name, for the two branded pages. Trimmed; 1 to 60 characters.\n\n- With `signup=hosted` (WhatsApp): replaces Zernio in the page title (\"Connect your WhatsApp number to <brandName>\").\n- With `welcome=true`: fills the heading (\"<brandName> wants to connect to your <platform>\"). Without it the screen shows Zernio and the Zernio mark.\n\nBoth pages keep a Zernio mark: they are co-branded, not white-label. Rejected with 400 `INVALID_FIELD_VALUE` without `signup=hosted` or `welcome=true`. Sealed into the page link at issue time, so editing the URL cannot change it.\n"},{"name":"primaryColor","in":"query","schema":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"description":"Hex colour (`#RRGGBB`) for the primary button on the hosted WhatsApp signup page (`signup=hosted`) or the welcome screen (`welcome=true`). Validated server-side; anything else is a 400 `INVALID_FIELD_VALUE`. Rejected without one of the two."},{"name":"welcome","in":"query","schema":{"type":"boolean"},"description":"Any platform. When `true`, `authUrl` points to a Zernio-hosted welcome screen showing your brand next to the platform (\"<brandName> wants to connect to your <platform>\"). Its button reads Connecting for about a second, then sends the user to the platform's authorization screen with no click.\n\nThe rest of the flow is unchanged.\n\n- `brandName`, `logoUrl`, `primaryColor` and `welcomeTheme` are optional and default to Zernio's own name, mark and look.\n- The link is valid for 30 minutes; after that the page asks the user to start again.\n- The brand also carries to the account and channel pickers Zernio shows after authorization.\n- With no `redirect_url`, the flow ends on a branded Zernio-hosted page saying whether the account connected, instead of the Zernio dashboard.\n- Cannot be combined with `headless=true` or `signup=hosted` (400 `INVALID_FIELD_VALUE`).\n- The platform's authorization screen still names the Zernio app.\n\nRecommended. When left out, the screen is shown if the workspace saved it as on by default (`PUT /v1/connect/welcome-screen`), except with `headless=true` or `signup=hosted`. Pass `false` to skip it.\n\nBranding you leave out of the call comes from those saved settings, and a `welcomeTheme` you send is merged key by key over the saved theme.\n"},{"name":"welcomeTheme","in":"query","schema":{"type":"string","maxLength":4000},"description":"Welcome screen only (`welcome=true`). A URL-encoded JSON object that restyles and rewords the screen. All keys are optional.\n\n- **Copy**: `heading` (up to 120 characters); `trustLine`, `consentLine` and `statusLine` (up to 200 each, `statusLine` being the line above the button); `buttonLabel` (up to 30, the label of the link the button becomes if the redirect stalls).\n- **Closing page** (shown when there is no `redirect_url`): `successHeading` and `errorHeading` (up to 120), `successBody` and `errorBody` (up to 200). All copy may contain the placeholders `{brand}` and `{platform}`.\n- **Colors**: `primaryColor` (the button), `accentColor` (the header gradient, built as a scale of that colour, and the icons), `pageColor`, `cardColor` and `textColor`, all as `#RRGGBB`.\n- **Style**: `cornerRadius` as an integer from 0 to 24 (pixels); `font` as `sans`, `serif` or `mono`; `bannerStyle` as `halftone` (default), `solid` (a flat tint of `accentColor`) or `plain` (no banner fill).\n- **Icons**: `trustLineIcon` (default `shield`) and `consentLineIcon` (default `link`), each one of `shield`, `lock`, `link`, `check`, `user`, `sparkles` or `none`.\n- **Visibility**: `hide`, an array of any of `heading`, `trustLine`, `consentLine`, `statusLine`, `successBody` and `errorBody`, removes those lines from the screens.\n- **Links**: `termsUrl` and `privacyUrl` (https, up to 2048 characters) add small Terms and Privacy links at the bottom of every hosted screen.\n\nA `primaryColor` here wins over the `primaryColor` parameter. Unknown keys, invalid JSON or an invalid value are a 400 `INVALID_FIELD_VALUE`. Rejected when the welcome screen is not shown.\n\nExample: `{\"heading\":\"Link your {platform} to {brand}\",\"cardColor\":\"#FFF7ED\",\"cornerRadius\":12}`.\n"},{"name":"logoUrl","in":"query","schema":{"type":"string","format":"uri","maxLength":2048},"description":"Welcome screen only (`welcome=true`): https URL of your logo, shown in a square tile, so use a square image. Without it the tile shows the first letter of `brandName`, or the Zernio mark when there is no `brandName` either. Rejected with 400 `INVALID_FIELD_VALUE` when the welcome screen is not shown."},{"name":"language","in":"query","schema":{"type":"string","enum":["en","es","pt-BR"]},"description":"Hosted signup page only (`signup=hosted`, WhatsApp): language of the page and its follow-along guide. Explainer videos stay in English. Default `en`. Rejected without `signup=hosted`."},{"name":"handoff","in":"query","schema":{"type":"boolean","default":false},"description":"Let the user finish on their phone. When `true`, the response also carries `handoff`. Show `handoff.url` as a QR code in your app (any QR library); the user scans it and the welcome screen opens on the phone, already carrying this connect.\n\nThey log in to the platform there without signing in to anything else. The phone ends on a Zernio result screen telling them to go back to their computer.\n\n- Learn the outcome by polling `GET /v1/connect/handoffs/{handoffId}` (every 2 to 5 seconds is fine) or from the `account.connected` webhook.\n- Shows the welcome screen with your branding parameters or saved settings.\n- Cannot be combined with `welcome=false`, `headless=true`, `signup`, `redirect=true` or `redirect_url` (400 `INVALID_FIELD_VALUE`).\n- `handoff.url` works for 30 minutes.\n- When the account is re-enabled straight away, the response carries `account` instead, as without `handoff`.\n"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OAuth authorization URL to redirect user to","content":{"application/json":{"schema":{"type":"object","properties":{"authUrl":{"type":"string","format":"uri","description":"URL to redirect your user to for OAuth authorization"},"state":{"type":"string","description":"State parameter for security (handled automatically)"},"handoff":{"$ref":"#/components/schemas/ConnectHandoffLink"}}},"example":{"authUrl":"https://www.facebook.com/v21.0/dialog/oauth?client_id=...","state":"user123-profile456-1234567890-https://yourdomain.com/callback"}}}},"400":{"x-summary":"The connect request has missing or invalid parameters, like a bad profile ID or a relative redirect URL: fix them and retry.","description":"Missing/invalid parameters (e.g., invalid profileId format, a non-absolute redirect_url, or a redirect_url too long for X's 500-character state)"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"No access to profile, BYOK required for AppSumo X, or Snapchat closed beta (code PLATFORM_BETA_RESTRICTED)"},"404":{"description":"Profile not found"}}},"post":{"x-resource-group":"accounts","operationId":"handleOAuthCallback","tags":["Connect"],"summary":"Complete OAuth callback","description":"Exchange the OAuth authorization code for tokens and connect the account to the specified profile.\n\nFacebook, Google Business Profile, Snapchat and WhatsApp are not accepted here: their account identity is a destination chosen after OAuth, which this single-shot exchange cannot do. Connect them through the redirect flow from `GET /v1/connect/{platform}`, or, for WhatsApp Embedded Signup, through `POST /v1/connect/whatsapp/embedded-signup`.\n","parameters":[{"name":"platform","in":"path","required":true,"description":"Social platform to complete the connect for. Discord, Slack and Telegram are absent because they are\nserved by their own dedicated routes, documented separately.\n","schema":{"type":"string","enum":["instagram","twitter","threads","linkedin","youtube","tiktok","reddit","pinterest","google","microsoft"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","state","profileId"],"properties":{"code":{"type":"string"},"state":{"type":"string","description":"For twitter, the state X returned on the redirect (the same as the state query parameter of authUrl, ending in its -cv_ PKCE verifier suffix), signed and under 1 hour old. The state field of the GET JSON response does not carry the verifier."},"profileId":{"type":"string"}}}}}},"responses":{"200":{"description":"Account connected"},"400":{"x-summary":"The callback is invalid because a destination must be chosen, or the state is missing, invalid or expired: fix it and retry.","description":"Invalid params, the platform requires choosing a destination (code: platform_requires_destination), or an X state without the verifier or with an invalid or expired signature (code: invalid_field_value, param: state)"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"No access to the profile, or BYOK required for AppSumo X"},"404":{"description":"Profile not found"},"500":{"description":"Internal error while connecting the account"},"502":{"description":"The platform rejected the token exchange (type: platform_error; an upstream 4xx status is forwarded instead of 502)"},"503":{"description":"Connections for this platform are temporarily disabled (code: platform_disabled)"}}}},"/v1/connect/{platform}/ads":{"get":{"x-resource-group":"accounts","operationId":"connectAds","tags":["Connect"],"x-platforms":["meta","linkedin","tiktok","twitter","pinterest","google","reddit"],"summary":"Connect ads for a platform","description":"Starts connecting a platform's ads account, giving you a dedicated ads connection to manage campaigns without touching posting accounts. It creates a dedicated ads SocialAccount for the specified platform.\n\nAds accounts appear as regular SocialAccount documents with ads platform values (e.g., metaads, tiktokads) in GET /v1/accounts.\n\n### Meta business login (opt-in)\n\nSet `loginMode=business` for `facebook` or `instagram` to use Facebook Login for Business and a Business Integration System User token. No posting account is created or required.\n\nThis mode always returns an authUrl. It returns 503 when the server has no META_ADS_CONFIG_ID. Complete the dialog in a browser.\n\nThe callback creates or reconnects only the metaads account, preserving its ID and history. Non-empty successful subscription results replace subscribedAdAccountIds to remove stale grants; an empty result leaves routing unchanged.\n\n#### Reconnecting\n\nA reconnect is accepted when the new grant shares at least one ad account with the existing connection, so re-running the dialog can add, drop or swap ad accounts.\n\nThe existing connection's ad accounts are its scopedAdAccountIds plus the previous grant, or the ad accounts its old token can read when neither is stored.\n\n- A grant with zero overlap is refused before changing the account and redirects with `error=invalid_field_value` and `error_reason=reconnect_mismatch` (disconnect and connect again to switch).\n- When the previous ad accounts cannot be read at all, it redirects with `error=reconnect_required`.\n\nOn an accepted reconnect the scope is rebuilt from the new grant:\n\n- `adAccountIds` passed on the re-auth become the scope.\n- Otherwise a stored scope keeps its ad accounts that are still granted, plus any granted for the first time.\n- An unscoped connection follows the new grant.\n\n#### Page selection\n\nPass `pageId` to select a granted Page for creatives and lead forms. API integrations otherwise reuse the previous Page or the sole granted Page.\n\nMultiple Pages without a selection return 400 with available Page IDs for API integrations; restart with pageId. Dashboard session logins use the sole current grant automatically, or open the existing Facebook Page picker for several grants, including reconnects. Selection completes the Meta Ads connection.\n\n#### Result redirects\n\nSuccess redirects with connected=metaads, profileId and accountId.\n\nEvery failure after Meta's dialog redirects to redirect_url (or the dashboard) with `error`, `platform=metaads`, `error_message`, `request_id` and `stage`, plus `is_user_fixable` and `error_reason` when known. `error` is the API error code:\n\n- `invalid_field_value`, with `error_reason`:\n  - `no_pages_granted`: no Page ticked\n  - `page_not_granted`: pageId not in the grant\n  - `ad_accounts_not_granted`\n  - `reconnect_mismatch`: the grant shares no ad account with the existing connection\n- `reconnect_required`, `ads_addon_required`, `payment_required` and the profile gates of GET /v1/connect/{platform}\n- `invalid_state` with `error_reason=state_expired`: after the 30-minute window\n- `connection_failed`: Meta refuses the code (e.g. a replayed callback)\n- `meta_ads_authorization_denied`: a denial in the dialog, with the `platform_error*` params\n\nOnly a state that cannot be decrypted at all still answers 400 JSON, since it names no redirect_url.\n\n#### Tokens\n\nBusiness login reports metadata.tokenType=system-user in GET /v1/accounts. An absent Meta expires_in leaves tokenExpiresAt absent; no personal-token re-exchange occurs.\n\nSubsequent classic requests can change the ad-account scope using the business token. force=true (or disconnecting the business connection first) switches the profile to the standard Facebook login; the ads account is then held by the user token.\n\n### Same-token platforms (facebook, instagram, linkedin, pinterest)\n\nThe ads SocialAccount (metaads, linkedinads, pinterestads) reuses the OAuth token of the parent posting account, but only when:\n\n- an active parent exists, and\n- for facebook and instagram, its stored token carries ads_management and ads_read (linkedin and pinterest need no extra scope).\n\nIn that case no extra OAuth happens and the response is alreadyConnected: true.\n\nWhen no such parent exists, or the scopes are missing, the endpoint returns an authUrl and a full OAuth round trip is required.\n\nErrors:\n\n- 400 RECONNECT_REQUIRED: a parent exists but carries no token usable for ad accounts\n- 403 ADS_ADDON_REQUIRED: no ads add-on (independently of the branch)\n- 402 PAYMENT_REQUIRED: the billing gate is closed (independently of the branch)\n\n#### Meta Ads needs a Facebook Page\n\nConnecting Meta Ads (via facebook or instagram) requires a Facebook Page. Not because the ad account is read through a Page, but because both parent posting accounts are:\n\n- the facebook flow only offers Pages you manage\n- the instagram flow with loginMethod=facebook_login only offers Instagram accounts linked to one of those Pages\n\nWithout a Page there is no parent account to inherit a token from. A user who manages no Facebook Page cannot complete this connection, and the facebook flow ends with error=no_facebook_pages.\n\n### Separate-token platforms (tiktok, twitter)\n\nStarts the platform-specific marketing API OAuth flow and creates an ads SocialAccount (tiktokads, xads) with its own token. If the ads account already exists, returns alreadyConnected: true.\n\n- twitter (X Ads): accountId is REQUIRED. There's no ads-only mode, because tweets need to be authored by a real X user.\n- tiktok: accountId is OPTIONAL.\n\n#### TikTok with or without accountId\n\n- With accountId, the new tiktokads account links to that posting account (parentAccountId set), so Spark Ads + standalone ads using the posting TT_USER identity become available.\n- Without accountId, ads-only mode kicks in: the new tiktokads account has parentAccountId=null and standalone ads use a synthetic CUSTOMIZED_USER (\"Brand Identity\"). Spark Ads are unavailable because TikTok requires a posting account for them.\n\nThe Brand Identity is configured separately via PATCH /v1/connect/tiktok-ads (or inline on POST /v1/ads/create via the brandIdentity field).\n\n### Standalone platforms (googleads)\n\nStarts the Google Ads OAuth flow and creates a standalone ads SocialAccount (googleads) with no parent.\n\n- If the account already exists and has at least one discovered Google Ads customer account, returns alreadyConnected: true.\n- When the existing connection has zero customer accounts (metadata.googleAdsCustomerIds is empty) or is flagged needsReconnection, it returns an authUrl instead. Completing it reconnects the same account (same accountId) and re-runs ad account discovery.\n\nDiscovery includes the client accounts under every manager (MCC) the Google user can reach. It also includes Google Ads test accounts, which Google always reports with status CLOSED.\n\nWhen discovery finds no usable customer account, the callback saves nothing and redirects with `error=google_ads_no_ad_accounts`, `platform=googleads` and an `error_message`.\n\nThe message names each customer the Google user can reach and why it was left out (for example CUSTOMER_NOT_ENABLED). Sign in with a Google user that has access to the ad account or to its manager account.\n\nWhen the user unticks the Google Ads permission on Google's consent screen, the callback saves nothing and redirects with `error=missing_google_permissions`, `platform=googleads`, `is_user_fixable=true` and `missing_scopes`.\n\nAn existing connection whose token lacks that permission is flagged needsReconnection, and the health endpoints report \"Google Ads permission not granted\". This endpoint then returns an authUrl for it.\n\n### Standalone platforms (redditads)\n\nStarts the Reddit Ads OAuth flow (Reddit permissions `adsread`, `adsedit` and `adsconversions`) and creates a standalone ads SocialAccount (redditads) with no parent, separate from any organic `reddit` posting account. It is reached only as `redditads` in the path.\n\nIf an active Reddit Ads connection already exists on the profile, is not flagged needsReconnection and holds every one of those permissions, returns alreadyConnected: true. Otherwise it returns an authUrl; completing it reconnects the same account (same accountId).\n\nA connection authorized without `adsconversions` keeps managing ads, but:\n\n- the health endpoints list an issue asking to reconnect Reddit Ads and allow every permission\n- the Conversions API answers 403 `reconnect_required`\n- this endpoint returns an authUrl for it\n\nDiscovery lists every Reddit ad account the Reddit user can reach. The callback redirects with `platform=redditads` and:\n\n- `error=reddit_ads_scope_not_granted`: the user unticks `adsread` or `adsedit` on Reddit's consent screen (nothing is saved)\n- `error=reddit_ads_no_ad_accounts`: the user reaches no Reddit ad account\n\nWithout `redirect_url` the browser lands on the Zernio dashboard's ad account picker for the new connection.\n\n### Standalone platforms (microsoftads)\n\nStarts the Microsoft Advertising OAuth flow and creates a standalone ads SocialAccount (microsoftads) with no parent. It is reached only as `microsoftads` in the path.\n\nMicrosoft Advertising users sign in with a Microsoft account by default. A user who signs in to ads.microsoft.com with Google passes `identityProvider=google`, and the flow runs on Google's consent screen instead.\n\nIf an active Microsoft Ads connection already exists on the profile, is not flagged needsReconnection and was signed in with the same identity provider, returns alreadyConnected: true. Otherwise it returns an authUrl; completing it reconnects the same account (same accountId).\n\nDiscovery lists every Microsoft Advertising ad account the user can reach. The callback redirects with `platform=microsoftads` and:\n\n- `error=microsoft_ads_scope_not_granted`: the user declines the Microsoft Advertising permission (nothing is saved)\n- `error=microsoft_ads_unknown_user`: the account that signed in is not a Microsoft Advertising user, for example a Google user connecting without `identityProvider=google` (nothing is saved)\n- `error=microsoft_ads_no_ad_accounts`: the user reaches no Microsoft Advertising ad account\n\nWithout `redirect_url` the browser lands on the Zernio dashboard's ad account picker for the new connection.\n","parameters":[{"name":"identityProvider","in":"query","schema":{"type":"string","enum":["microsoft","google"],"default":"microsoft"},"description":"Microsoft Ads only. How the user signs in to Microsoft Advertising: `google` for a Microsoft Advertising login that is a Google account. `google` on any other platform returns 400 `invalid_field_value`.","example":"google"},{"name":"loginMode","in":"query","schema":{"type":"string","enum":["classic","business"],"default":"classic"},"description":"Meta ads authorization mode. Business login is opt-in for Facebook and Instagram; classic preserves the posting-account flow.","example":"business"},{"name":"permissionLevel","in":"query","schema":{"type":"string","enum":["full","advertise"],"default":"full"},"description":"Business login only. Ad-account permission the connection's system user will hold.\n\n- `full`: asks the owner for Full control (MANAGE). Required to create pixels and other account-level assets through Zernio.\n- `advertise`: asks for Manage campaigns (ADVERTISE), enough for campaigns, ad sets, creatives, ads, media and reporting. For owners who will not grant billing-level control to an integration.\n\nEither way, Meta only lets a business admin complete the grant. 503 if the advertise configuration is not set up.\n","example":"advertise"},{"name":"pageId","in":"query","schema":{"type":"string","pattern":"^\\d+$"},"description":"Business login only. Facebook Page ID to select from the token grants for ad creatives and lead forms.","example":"811889972008357"},{"name":"platform","in":"path","required":true,"schema":{"type":"string","enum":["facebook","instagram","linkedin","tiktok","twitter","pinterest","googleads","redditads","microsoftads"]},"description":"Platform to connect ads for. Only platforms with ads support are accepted.\n\nIn classic mode, `instagram` requires an Instagram account connected with loginMethod=facebook_login whose\ntoken carries ads_management and ads_read. With an account connected through the default\ninstagram_login flow no ads account can be created; do not use this value for those accounts.\n"},{"name":"profileId","in":"query","required":true,"schema":{"type":"string"},"description":"Your Zernio profile ID"},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Existing SocialAccount ID.\n\n- `twitter` (X Ads): required.\n- `tiktok`: optional. Omit it for ads-only mode (no TikTok posting account linked; ad creation uses a Brand Identity instead of a TT_USER).\n- Same-token platforms (`facebook`, `instagram`, `linkedin`, `pinterest`): picks which posting account the ads connection uses when the profile holds several of that platform. With one, it can be omitted.\n- Standalone platforms (`googleads`, `redditads`, `microsoftads`): ignored.\n\nOn same-token platforms, an id that names no active account of the platform on the profile is ignored. Exception: with `force=true`, when it names the posting account the profile's ads connection hangs off, that account is no longer connected.\n\nIn that case the call returns 409 `reconnect_required` instead of reconnecting another account. Reconnect it via GET /v1/connect/{platform} first.\n"},{"name":"redirect_url","in":"query","schema":{"type":"string","format":"uri"},"description":"Custom URL the browser is sent to once the OAuth flow finishes. When omitted, the browser lands on the Zernio dashboard. Honored on every ads platform, including the separate-token (`tiktok`, `twitter`) and standalone (`googleads`, `redditads`, `microsoftads`) flows.\n\nMUST be an absolute http(s) URL or a custom app scheme for mobile deeplinks (e.g. myapp://callback). A relative path is rejected with 400 INVALID_REDIRECT_URL.\n\nOn success:\n\n- `tiktok`: lands on the URL unchanged.\n- `twitter`, `googleads`, `redditads` and `microsoftads`: append `connected` (the ads platform id: `xads`, `googleads`, `redditads` or `microsoftads`), `profileId`, `accountId` (the ads connection) and `username`.\n- Same-token platforms (`facebook`, `instagram`, `linkedin`, `pinterest`): append `connected`, `profileId`, `accountId`, `username` and, on API-key calls, `connect_token`.\n\nOn failure the same error contract applies as on GET /v1/connect/{platform}: `error` and `platform` are always appended, other params are optional, and the value list there is not exhaustive.\n\nOn the tiktok, twitter, googleads, redditads and microsoftads flows, `platform` carries the ads platform id (`tiktokads`, `xads`, `googleads`, `redditads`, `microsoftads`), not the value used in the request path.\n"},{"name":"headless","in":"query","schema":{"type":"boolean","default":false},"description":"Enable headless mode (same-token platforms only)"},{"name":"force","in":"query","schema":{"type":"boolean","default":false},"description":"Force a fresh OAuth even when an account already exists.\n\nNormally the endpoint returns `alreadyConnected: true` whenever a connected account is found, keyed off its active state rather than token liveness. Set `force=true` to bypass that and always receive an `authUrl`. Completing the returned OAuth refreshes the stored token on the existing posting and ads accounts in place.\n\nAn `alreadyConnected` response re-runs ad discovery and webhook subscriptions in the background at most once every 15 minutes per ads account (always when the call changes the ad-account scope), so it is not a sync trigger.\n\nTo check the connection's health, read GET /v1/ads/accounts?accountId=<ads account ID>.\n"},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"Scopes ad sync to a single platform ad account. Without it, sync covers every ad account the connected token can see. For multiple accounts use `adAccountIds` instead.\n\nSupported on:\n\n- `facebook`/`instagram` (Meta): `act_<digits>`.\n- `linkedin`: bare numeric sponsored-account id.\n- `googleads`: bare customer id digits.\n- `redditads`: Reddit ad account id, `a2_<id>` or `t2_<id>`.\n- `microsoftads`: bare numeric account id (the Id, not the account number).\n- `twitter` (X Ads): base36 account id.\n\n`tiktok` scopes advertisers at OAuth and `pinterest` has no ads discovery, so both ignore it.\n\n**Meta validation** against the connected token:\n\n- An id the token cannot see returns 400 `invalid_field_value`.\n- An id it can see but that Meta marks unusable for ads (disabled, closed, under risk review, settlement pending) returns 400 `ad_account_unusable` with `details.accountStatus` (Meta's `account_status`) and, when Meta gives one, `details.disableReason`.\n- Unsettled and in-grace accounts are accepted, matching the `selectable` flag of `GET /v1/ads/accounts`.\n\n**Effects**: setting a scope removes already synced ads, campaigns, ad sets and keywords from de-scoped ad accounts. On Meta it also decides which ad accounts Zernio subscribes to ad-account webhooks: only the scoped ones, instead of every ad account the login can reach.\n\n**Through OAuth**: on Meta the scope is kept when this call returns an `authUrl`, so the Meta Ads account created after OAuth is scoped (only its scoped ad accounts synced and subscribed) from the start.\n\nOn `googleads`, `redditads` and `microsoftads` it is kept through OAuth when `redirect_url` is set, so the new connection syncs only scoped ad accounts from the first sync.\n\n**Reconnects**: business-login reconnects preserve the existing scope; supplied IDs are checked against the new grant. To change the scope after migration, call this endpoint with the IDs and omit loginMode.\n","example":"act_1330190928038136"},{"name":"adAccountIds","in":"query","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"description":"Scope ad sync to multiple platform ad accounts (same platform support and id shapes as `adAccountId`). Repeat the param (`?adAccountIds=act_1&adAccountIds=act_2`) or comma-separate (`?adAccountIds=act_1,act_2`).\n\n- Persisted server-side; the latest call wins. De-scoped ad accounts have their synced ads, campaigns, ad sets and keywords removed.\n- On Meta only the scoped ad accounts get webhook subscriptions, including when the call starts a fresh OAuth.\n- Omitting both `adAccountId` and `adAccountIds` keeps any previously persisted scope unchanged (no scope means every reachable ad account).\n"},{"name":"welcome","in":"query","schema":{"type":"boolean"},"description":"When `true`, `authUrl` opens on the Zernio-hosted welcome screen with your brand, as on GET /v1/connect/{platform}, naming the ads platform (\"<brandName> wants to connect to your Meta Ads\").\n\n- With no `redirect_url`, the flow ends on the branded result page instead of the Zernio dashboard.\n- Shown only with `welcome=true`: the workspace's saved \"on by default\" (`PUT /v1/connect/welcome-screen`) applies to GET /v1/connect/{platform} only, so ads links behave as before unless you opt in. The saved brand still fills in what the call leaves out.\n- Without `adAccountId` or `adAccountIds`, on Meta, Google, LinkedIn, X, Reddit and Microsoft, the user then picks the ad accounts to connect on a branded Zernio-hosted page (skipped when the login reaches only one).\n- After that page the flow ends on your `redirect_url` with `connected` set to the ads platform and `accountId` to the ads connection.\n- Cannot be combined with `headless=true` (400 `INVALID_FIELD_VALUE`).\n- Responses with `alreadyConnected: true` carry no `authUrl`, so they show no screen.\n"},{"name":"brandName","in":"query","schema":{"type":"string","minLength":1,"maxLength":60},"description":"Welcome screen only: your product name in its heading. Same rules as on GET /v1/connect/{platform}."},{"name":"logoUrl","in":"query","schema":{"type":"string","format":"uri","maxLength":2048},"description":"Welcome screen only: https URL of your square logo. Rejected with 400 `INVALID_FIELD_VALUE` when the welcome screen is not shown."},{"name":"primaryColor","in":"query","schema":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"description":"Welcome screen only: hex colour (`#RRGGBB`) of its button."},{"name":"welcomeTheme","in":"query","schema":{"type":"string","maxLength":4000},"description":"Welcome screen only: a URL-encoded JSON object restyling and rewording the welcome screen and the result page, with the keys documented on GET /v1/connect/{platform}. Rejected when the welcome screen is not shown."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Either an OAuth URL to redirect to, or confirmation that ads are already connected","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Ads already connected (no OAuth needed)","properties":{"alreadyConnected":{"type":"boolean","example":true},"accountId":{"type":"string"},"platform":{"type":"string"},"username":{"type":"string"},"displayName":{"type":"string"},"tokenType":{"type":"string","enum":["system-user"],"description":"Present for an existing business-login connection."},"scopedAdAccountIds":{"type":"array","items":{"type":"string"},"description":"Echo of the persisted ad-account scope when the caller passed\n`adAccountId` / `adAccountIds`. Omitted when no scope is set.\n","example":["act_1330190928038136"]}}},{"type":"object","description":"OAuth URL to redirect user to","properties":{"authUrl":{"type":"string","format":"uri"},"state":{"type":"string"}}}]},"examples":{"alreadyConnected":{"summary":"Same-token platform (Meta) with existing account","value":{"alreadyConnected":true,"accountId":"664a1b2c3d4e5f6789012345","platform":"instagram","username":"@mybrand","displayName":"My Brand"}},"businessLogin":{"summary":"Meta ads business login","value":{"authUrl":"https://www.facebook.com/v24.0/dialog/oauth?client_id=APP_ID&config_id=CONFIG_ID&response_type=code&override_default_response_type=true&redirect_uri=https%3A%2F%2Fzernio.com%2Fapi%2Fv1%2Fconnect%2Fmeta-ads%2Fcallback&state=ENCRYPTED_STATE","state":"ENCRYPTED_STATE"}},"oauthRequired":{"summary":"Separate-token platform (TikTok) needing ads OAuth","value":{"authUrl":"https://business-api.tiktok.com/portal/auth?app_id=...","state":"user123-profile456-account789-1234567890"}}}}}},"400":{"description":"Platform doesn't support ads, missing accountId for X Ads, or a non-absolute redirect_url"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads access required (Ads add-on on legacy plans, included on usage-based plans), or no access to profile"},"404":{"description":"Profile or posting account not found"},"409":{"x-summary":"The ads connection conflicts with the existing connection, like one needing reconnection or several matching accounts: follow the message.","description":"Conflict. One of:\n\n- The Business Login connection needs reconnecting: reconnect it with loginMode=business, or pass force=true or disconnect it first to switch to the standard login.\n- ambiguous_account: the profile holds several active accounts of the platform and no accountId names one.\n- reconnect_required: force=true names the posting account the ads connection hangs off, and it is no longer connected.\n"},"503":{"description":"Business login is not configured or the platform is temporarily unavailable."}}}},"/v1/connect/meta-ads/callback":{"get":{"x-resource-group":"public","operationId":"completeMetaAdsBusinessLogin","summary":"Complete Meta business login","tags":["Connect"],"x-platforms":["meta"],"security":[],"description":"Finishes a Meta business login after the user approves access, connects the Meta ads account and sends them back to your app.\n\nThis is the Facebook Login for Business redirect target. Meta supplies the single-use authorization code and the authenticated state returned by connectAds. No bearer token is sent by the browser.\n\nThe state expires after 30 minutes and binds the user, profile, Page selection and ad-account scope.\n\n### Outcomes\n\n- Success reconnects only metaads and redirects to the original redirect_url.\n- Invalid state returns 400.\n- Inaccessible profiles or missing ads access cannot connect.\n- Dashboard logins with several Pages redirect to the Facebook Page picker with an encrypted selectionToken valid for ten minutes. Listing and selecting require the initiating user and current profile access.\n\nNo plaintext platform token is returned to the browser.\n","parameters":[{"name":"state","in":"query","required":true,"schema":{"type":"string"},"description":"Authenticated state from the initial connectAds response.","example":"ENCRYPTED_STATE"},{"name":"code","in":"query","schema":{"type":"string"},"description":"Single-use authorization code returned by Meta."},{"name":"error","in":"query","schema":{"type":"string"},"description":"Meta authorization error when the user declines the dialog."}],"responses":{"307":{"x-summary":"The callback redirects to the original callback URL with the connected account details, or with an error if authorization was denied.","description":"Redirect to the original callback URL with connected=metaads, profileId and accountId on success; authorization denial redirects with an error. Dashboard logins requiring a Page choice redirect to /connect/facebook/select-page with selectionToken.","headers":{"Location":{"schema":{"type":"string","format":"uri"},"example":"https://example.com/callback?connected=metaads&profileId=PROFILE_ID&accountId=ACCOUNT_ID"}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"Ads access or profile access required."},"409":{"description":"The new token grants do not match the existing connection, or its previous grants cannot be verified."},"503":{"description":"Business login state signing is not configured."}}}},"/v1/connect/shopify":{"get":{"x-resource-group":"accounts","operationId":"getShopifyConnectUrl","tags":["Connect"],"summary":"Get Shopify OAuth connect URL","description":"Initiate the Shopify OAuth flow for a store. Returns an `authUrl` to redirect the merchant to.\n\nShopify is a connect-only platform: the connected account does not publish social posts. It powers the Blogs API (`/v1/accounts/{accountId}/blogs`) and the Products API (`/v1/accounts/{accountId}/products`).\n\n### Flow\n\n1. Redirect the merchant to `authUrl`.\n2. After they approve the install, Shopify redirects their browser to Zernio's callback, and the account is created on the profile (platform `shopify`).\n3. The browser is redirected to `redirect_url` with `connected`, `profileId`, `accountId` and `username` (the store's myshopify.com domain) added, or to the Zernio dashboard when omitted.\n\nThe account is the store the merchant approved, which can differ from `shop`, so bind on `accountId`.\n\n### Scopes\n\nRequested scopes are `read_content`, `write_content`, `read_products` and `write_products` (content and products only; no customer or order data).\n\nConnecting the same profile to a store again refreshes the stored token in place. This is how a store connected under the older content-only grant picks up product access.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"profileId","in":"query","required":true,"schema":{"type":"string"},"description":"Your Zernio profile ID (get from /v1/profiles)."},{"name":"shop","in":"query","required":true,"schema":{"type":"string"},"description":"The myshopify.com store domain to connect, e.g. `your-store.myshopify.com` (the bare `your-store` prefix is accepted too)."},{"name":"redirect_url","in":"query","schema":{"type":"string","format":"uri"},"description":"Your custom redirect URL after connection completes. MUST be an absolute http(s) URL or a custom app scheme for mobile deeplinks (e.g. myapp://callback); a relative path is rejected with 400 INVALID_REDIRECT_URL. On failure an `error` query param is appended."}],"responses":{"200":{"description":"OAuth authorization URL to redirect the merchant to","content":{"application/json":{"schema":{"type":"object","properties":{"authUrl":{"type":"string","format":"uri","description":"URL to redirect your user to for OAuth authorization"},"state":{"type":"string","description":"State parameter for security (handled automatically)"}}}}}},"400":{"x-summary":"The request is invalid because the profile ID, the store domain or the redirect URL is malformed: fix it and retry.","description":"Invalid `profileId` format, `shop` is not a myshopify.com store domain, or `redirect_url` is not an absolute http(s) URL or custom app scheme."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"API key does not have access to this profile."},"404":{"description":"Profile not found or access denied."},"500":{"description":"Shopify API not configured (missing credentials)."}}}},"/v1/connect/shopify/token":{"post":{"x-resource-group":"accounts","operationId":"connectShopifyWithToken","tags":["Connect"],"summary":"Connect a Shopify store with a custom-app Admin token","description":"Token-paste alternative to the OAuth flow: connect a store using the Admin API access token of a custom app the merchant created in their own Shopify admin.\n\nThe custom app is created under Settings → Apps and sales channels → Develop apps, with the `read_content`, `write_content`, `read_products` and `write_products` scopes.\n\nUse this when the one-click OAuth connect is unavailable or when your users prefer not to install a third-party app on their store.\n\n- The token is validated against the store before anything is saved.\n- Custom-app tokens do not expire.\n- Connecting the same profile to a store again replaces the stored token in place.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","shop","accessToken"],"properties":{"profileId":{"type":"string","description":"Your Zernio profile ID (get from /v1/profiles)."},"shop":{"type":"string","description":"The myshopify.com store domain, e.g. `your-store.myshopify.com` (the bare `your-store` prefix is accepted too)."},"accessToken":{"type":"string","description":"Admin API access token of the merchant-created custom app (starts with `shpat_`)."}}}}}},"responses":{"200":{"description":"Store connected as a platform account","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"object","properties":{"_id":{"type":"string"},"platform":{"type":"string","enum":["shopify"]},"username":{"type":"string","description":"The myshopify.com domain of the connected store."},"displayName":{"type":"string"},"profileId":{"type":"string"}}}}}}}},"400":{"description":"Invalid `profileId` format, `shop` is not a myshopify.com store domain, or Shopify rejected the access token for that store."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"API key does not have access to this profile."}}}},"/v1/connect/googleanalytics":{"get":{"x-resource-group":"accounts","operationId":"getGoogleAnalyticsConnectUrl","tags":["Connect"],"summary":"Get Google Analytics OAuth connect URL","description":"Starts OAuth for Google Analytics (GA4). Each connected GA4 property becomes its own account with platform `googleanalytics`; it reads reports and does not post.\n\nRequested scope: `https://www.googleapis.com/auth/analytics.readonly`.\n\n### Flow\n\nRedirect the user to `authUrl`.\n\n- **One readable property:** Zernio connects it and redirects to `redirect_url` (or the dashboard) with `connected=googleanalytics`, `profileId`, `accountId` and `username` (the property name).\n- **Several properties:** the user first picks one on a Zernio-hosted page, which then redirects the same way.\n\n### Your own property picker\n\nAdd `headless=true` to `redirect_url`. Zernio then redirects there with `step=select_property`, `profileId`, `platform=googleanalytics` and a `pendingDataToken` for `GET /v1/connect/googleanalytics/properties` and `POST /v1/connect/googleanalytics/select-property`.\n\n### Errors\n\nOn failure the redirect carries `error`, `platform=googleanalytics` and `error_message`. Errors include:\n\n- `googleanalytics_scope_missing`: the user unticked Analytics access.\n- `googleanalytics_no_properties`\n","security":[{"bearerAuth":[]},{"connectToken":[]}],"parameters":[{"name":"profileId","in":"query","required":true,"schema":{"type":"string"},"description":"Your Zernio profile ID (get from /v1/profiles)."},{"name":"redirect_url","in":"query","schema":{"type":"string"},"description":"Custom redirect after connection. Must be an absolute http(s) URL or custom app scheme such as `myapp://callback`; relative and unsafe URLs return 400."},{"name":"reconnectAccountId","in":"query","schema":{"type":"string"},"description":"Zernio account ID of the Google Analytics account being reconnected. Picking a different property then fails instead of adding a second account."}],"responses":{"200":{"description":"OAuth authorization URL and authenticated state","content":{"application/json":{"schema":{"type":"object","required":["authUrl","state"],"properties":{"authUrl":{"type":"string","format":"uri","description":"Google URL to open in the user agent."},"state":{"type":"string","description":"Authenticated, expiring OAuth state handled by the callback."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"API key does not have access to this profile, or the key is read-only."},"404":{"description":"Profile not found or access denied."},"503":{"description":"Google Analytics OAuth is not configured."}}}},"/v1/connect/googleanalytics/properties":{"get":{"x-resource-group":"accounts","operationId":"listGoogleAnalyticsProperties","tags":["Connect"],"summary":"List Google Analytics properties for a pending connect","description":"For headless flows: lists the GA4 properties of a pending Google Analytics connect, so you can show your own picker.\n\n### Flow\n\n1. The connect started with `redirect_url=...?headless=true`, and the Google account can read several GA4 properties.\n2. Zernio redirects to your `redirect_url` with `step=select_property`, `profileId`, `platform=googleanalytics` and a `pendingDataToken`.\n3. Call this to list the properties and show your own picker.\n4. Call `POST /v1/connect/googleanalytics/select-property`.\n\n### Token\n\n- Listing does not consume the token.\n- A headless token passes through your own URLs, so it is honored only together with your API key (or connect token) for the same profile.\n- It expires after one hour.\n","security":[{"bearerAuth":[]},{"connectToken":[]}],"parameters":[{"name":"pendingDataToken","in":"query","required":true,"schema":{"type":"string"},"description":"Token from the headless redirect."}],"responses":{"200":{"description":"Properties the Google account can read","content":{"application/json":{"schema":{"type":"object","properties":{"properties":{"type":"array","items":{"type":"object","properties":{"propertyId":{"type":"string","description":"Numeric GA4 property ID.","example":"312456789"},"displayName":{"type":"string","example":"acme.com"},"accountId":{"type":"string","description":"Google Analytics account ID."},"accountName":{"type":"string","example":"Acme Inc"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The connect token was issued for a different profile or platform (INSUFFICIENT_PERMISSIONS)."},"404":{"x-summary":"The pending sign-in expired or was already used: start the connect again.","description":"The pending sign-in expired or was already used. Start the connect again."}}}},"/v1/connect/googleanalytics/select-property":{"post":{"x-resource-group":"accounts","operationId":"selectGoogleAnalyticsProperty","tags":["Connect"],"summary":"Connect the chosen Google Analytics property","description":"For headless flows. Connects the property the user picked as a `googleanalytics` account and returns where to send the user next.\n\n- On success: your `redirect_url` with `connected=googleanalytics`, `profileId`, `accountId` and `username`.\n- When the connect was refused (for example a billing block): an `error`.\n\nConsumes the `pendingDataToken`; a refused or failed attempt leaves it usable for a retry.\n\nSend your API key (or connect token) for the same profile with a headless token.\n","security":[{"bearerAuth":[]},{"connectToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pendingDataToken","propertyId"],"properties":{"pendingDataToken":{"type":"string","description":"Token from the headless redirect."},"propertyId":{"type":"string","description":"A propertyId from the properties list.","example":"312456789"}}}}}},"responses":{"200":{"description":"The property is connected, or the connect was refused with a reason in redirect_url","content":{"application/json":{"schema":{"type":"object","properties":{"redirect_url":{"type":"string","description":"Where to send the user next."},"account":{"type":["object","null"],"description":"The connected account, or null when the connect was refused.","properties":{"accountId":{"type":"string"},"platform":{"type":"string","example":"googleanalytics"},"username":{"type":"string"},"displayName":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"The connect token was issued for a different profile or platform (INSUFFICIENT_PERMISSIONS)."},"404":{"x-summary":"The pending sign-in expired or was already used: start the connect again.","description":"The pending sign-in expired or was already used. Start the connect again."},"500":{"x-summary":"Saving failed on the Google or Zernio side: the `pendingDataToken` stays usable, so retry.","description":"Google or Zernio failed while saving. The pendingDataToken stays usable; retry."}}}},"/v1/connect/hubspot":{"get":{"x-resource-group":"accounts","operationId":"getHubSpotConnectUrl","tags":["Connect"],"summary":"Get HubSpot OAuth connect URL","description":"Initiates OAuth for a HubSpot portal. HubSpot is a connect-only CRM platform: the connected account does not post, read analytics or run ads.\n\nOne HubSpot portal can be connected per profile. Connecting a different portal to a profile that already has one redirects with `error=hubspot_profile_has_portal`.\n\n### Flow\n\n1. Redirect the user to `authUrl`.\n2. After authorization, HubSpot returns the browser to Zernio's internal callback.\n3. Zernio redirects to `redirect_url` (or the dashboard when omitted).\n\nOn success the redirect carries `connected=hubspot`, `profileId`, `accountId` and `username` (the portal domain). On failure it carries `error`, `platform=hubspot` and `error_message`.\n\nReconnecting the same portal and profile updates the stored connection in place and keeps its settings.\n\nRequested scopes: `oauth`, `crm.objects.contacts.read`, `crm.objects.contacts.write`.\n","security":[{"bearerAuth":[]},{"connectToken":[]}],"parameters":[{"name":"profileId","in":"query","required":true,"schema":{"type":"string"},"description":"Your Zernio profile ID (get from /v1/profiles)."},{"name":"redirect_url","in":"query","schema":{"type":"string"},"description":"Custom redirect after connection. Must be an absolute http(s) URL or custom app scheme such as `myapp://callback`; relative and unsafe URLs return 400."}],"responses":{"200":{"description":"OAuth authorization URL and authenticated state","content":{"application/json":{"schema":{"type":"object","required":["authUrl","state"],"properties":{"authUrl":{"type":"string","format":"uri","description":"HubSpot URL to open in the user agent."},"state":{"type":"string","description":"Authenticated, expiring OAuth state handled by the callback."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"API key does not have access to this profile, or the key is read-only."},"404":{"description":"Profile not found or access denied."},"503":{"description":"HubSpot OAuth is not configured."}}}},"/v1/connect/wordpress":{"get":{"x-resource-group":"accounts","operationId":"getWordPressAuthUrl","tags":["Connect"],"summary":"Get WordPress.com OAuth connect URL","description":"Initiates OAuth for a WordPress.com site or a Jetpack-connected site.\n\nWordPress is a connect-only blog platform: the connected account powers the Blogs API (`/v1/accounts/{accountId}/blogs`). It does not support social posts, inbox, analytics, ads, or Shopify product operations.\n\n### Flow\n\n1. Redirect the user to `authUrl`.\n2. After authorization, WordPress returns the browser to Zernio's internal callback.\n3. Zernio redirects to `redirect_url` (or the dashboard when omitted).\n\nReconnecting the same site and profile updates the stored connection in place.\n\n### Scopes\n\nThe consent request omits `scope` to use WordPress.com's default single-site grant. Granular scopes cannot access the `/wp/v2` article API.\n\nZernio checks that API before saving the connection and does not request explicit `global` authorization across all sites.\n","security":[{"bearerAuth":[]},{"connectToken":[]}],"parameters":[{"name":"profileId","in":"query","required":true,"schema":{"type":"string"},"description":"Your Zernio profile ID (get from /v1/profiles)."},{"name":"redirect_url","in":"query","schema":{"type":"string"},"description":"Custom redirect after connection. Must be an absolute http(s) URL or custom app scheme such as `myapp://callback`; relative and unsafe URLs return 400."}],"responses":{"200":{"description":"OAuth authorization URL and authenticated state","content":{"application/json":{"schema":{"type":"object","required":["authUrl","state"],"properties":{"authUrl":{"type":"string","format":"uri","description":"WordPress.com URL to open in the user agent."},"state":{"type":"string","description":"Authenticated, expiring OAuth state handled by the callback."}}}}}},"400":{"description":"Invalid `profileId` or `redirect_url`."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"API key does not have access to this profile."},"404":{"description":"Profile not found or access denied."},"503":{"description":"WordPress.com OAuth or state signing is not configured."}}}},"/v1/connect/wix":{"get":{"x-resource-group":"accounts","operationId":"getWixConnectUrl","tags":["Connect"],"summary":"Get Wix site install URL","description":"Returns the Wix installer link for the Zernio app.\n\n### Flow\n\n1. The user picks one of their Wix sites there and approves the app.\n2. Wix returns the browser to Zernio's internal callback, which connects that site.\n3. The callback redirects to `redirect_url` (or the dashboard when omitted).\n\n### What the account supports\n\nWix is a connect-only blog platform. The connected account powers the Blogs API (`/v1/accounts/{accountId}/blogs`) and does not support social posts, inbox, analytics or ads. The site needs the Wix Blog app.\n\nAccess tokens renew by themselves. Removing the Zernio app from the site in Wix disconnects the account.\n","security":[{"bearerAuth":[]},{"connectToken":[]}],"parameters":[{"name":"profileId","in":"query","required":true,"schema":{"type":"string"},"description":"Your Zernio profile ID (get from /v1/profiles)."},{"name":"redirect_url","in":"query","schema":{"type":"string"},"description":"Custom redirect after connection. Must be an absolute http(s) URL or custom app scheme such as `myapp://callback`; relative and unsafe URLs return 400."}],"responses":{"200":{"description":"Wix installer URL and authenticated state","content":{"application/json":{"schema":{"type":"object","required":["authUrl","state"],"properties":{"authUrl":{"type":"string","format":"uri","description":"Wix installer URL to open in the user agent."},"state":{"type":"string","description":"Authenticated, expiring state handled by the callback."}}}}}},"400":{"description":"Invalid `profileId` or `redirect_url`."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"API key does not have access to this profile."},"404":{"description":"Profile not found or access denied."},"503":{"description":"The Wix app or state signing is not configured."}}}},"/v1/connect/webflow":{"get":{"x-resource-group":"accounts","operationId":"getWebflowConnectUrl","tags":["Connect"],"summary":"Get Webflow OAuth URL","description":"Returns Webflow's consent URL for the Zernio Webflow app.\n\n### Flow\n\n1. The user picks exactly one site on Webflow's consent screen.\n2. Webflow returns the browser to Zernio's internal callback, which connects that site.\n3. Zernio redirects to `redirect_url` (or the dashboard when omitted).\n\nPicking several sites connects none and redirects with `error=webflow_pick_one_site`.\n\n### Notes\n\n- Connecting a site already connected with a site token upgrades the same account.\n- Only an OAuth connection can install tracking tags on the site (`installTrackingTagOnStore`); blogs work with either.\n- The token does not expire.\n","security":[{"bearerAuth":[]},{"connectToken":[]}],"parameters":[{"name":"profileId","in":"query","required":true,"schema":{"type":"string"},"description":"Your Zernio profile ID (get from /v1/profiles)."},{"name":"redirect_url","in":"query","schema":{"type":"string"},"description":"Custom redirect after connection. Must be an absolute http(s) URL or custom app scheme such as `myapp://callback`; relative and unsafe URLs return 400."}],"responses":{"200":{"description":"Webflow consent URL and authenticated state","content":{"application/json":{"schema":{"type":"object","required":["authUrl","state"],"properties":{"authUrl":{"type":"string","format":"uri","description":"Webflow consent URL to open in the user agent."},"state":{"type":"string","description":"Authenticated, expiring state handled by the callback."}}}}}},"400":{"description":"Invalid `profileId` or `redirect_url`."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"API key does not have access to this profile."},"404":{"description":"Profile not found or access denied."},"503":{"description":"The Webflow app or state signing is not configured."}}}},"/v1/connect/webflow/token":{"post":{"x-resource-group":"accounts","operationId":"connectWebflowWithSiteToken","tags":["Connect"],"summary":"Connect Webflow with a site API token","description":"Connects one Webflow site using a site API token. Zernio checks the token's scopes, reads its site, and stores the token encrypted.\n\nCreate the token in the site's Site settings > Apps & integrations > API access, with Sites read-only and CMS read and write access.\n\n### What it supports\n\nWebflow is a connect-only blog platform: each CMS collection with a rich text field is a blog in the Blogs API (`/v1/accounts/{accountId}/blogs`). It does not support social posts, inbox, analytics or ads.\n\n- Publishing an article needs a site that has been published once.\n- Reconnecting the same site and profile updates the connection in place.\n","security":[{"bearerAuth":[]},{"connectToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["profileId","siteToken"],"properties":{"profileId":{"type":"string","description":"Your Zernio profile ID (get from /v1/profiles)."},"siteToken":{"type":"string","minLength":1,"maxLength":512,"writeOnly":true,"description":"Webflow site API token with Sites read and CMS read and write access."}}}}}},"responses":{"200":{"description":"Webflow site connected as a platform account","content":{"application/json":{"schema":{"type":"object","required":["account"],"properties":{"account":{"type":"object","required":["_id","platform","username","displayName","profileId"],"properties":{"_id":{"type":"string"},"platform":{"type":"string","enum":["webflow"]},"username":{"type":"string","description":"Hostname of the connected Webflow site."},"displayName":{"type":"string","description":"Webflow site name."},"profileId":{"type":"string"}}}}}}}},"400":{"description":"Malformed body, or a token Webflow rejects, that is not scoped to one site, or that lacks Sites read or CMS write access."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"API key does not have access to this profile."},"404":{"description":"Profile not found or access denied."},"502":{"description":"Webflow returned an unclassified upstream error."}}}},"/v1/connect/wordpress/token":{"post":{"x-resource-group":"accounts","operationId":"connectWordPressWithApplicationPassword","tags":["Connect"],"summary":"Connect self-hosted WordPress with an application password","description":"Connects one self-hosted WordPress site using a WordPress username and application password.\n\n- `siteUrl` must use HTTPS and may include the path where WordPress is installed.\n- Create an application password in the WordPress user's profile; do not send the user's login password.\n\nZernio discovers the REST API, verifies the credentials and required post/media/taxonomy capabilities, then stores the password encrypted.\n\nReconnecting the same site and profile updates the connection in place.\n","security":[{"bearerAuth":[]},{"connectToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["profileId","siteUrl","username","applicationPassword"],"properties":{"profileId":{"type":"string","description":"Your Zernio profile ID (get from /v1/profiles)."},"siteUrl":{"type":"string","format":"uri","pattern":"^https://","description":"HTTPS base URL of the WordPress installation, including a subdirectory path when applicable."},"username":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[^:\\r\\n]+$","description":"WordPress login name. A colon is not allowed."},"applicationPassword":{"type":"string","minLength":1,"maxLength":1024,"writeOnly":true,"description":"Application password created for the WordPress user. Spaces in WordPress display formatting are accepted."}}}}}},"responses":{"200":{"description":"WordPress site connected as a platform account","content":{"application/json":{"schema":{"type":"object","required":["account"],"properties":{"account":{"type":"object","required":["_id","platform","username","displayName","profileId"],"properties":{"_id":{"type":"string"},"platform":{"type":"string","enum":["wordpress"]},"username":{"type":"string","description":"Hostname of the connected WordPress site."},"displayName":{"type":"string","description":"WordPress site title."},"profileId":{"type":"string"}}}}}}}},"400":{"x-summary":"The request is invalid, like a malformed body, a non-HTTPS site URL, a bad username or an unsupported site: fix it.","description":"Malformed body, non-HTTPS `siteUrl`, invalid username, unavailable REST API, or a site that cannot support the required WordPress operations."},"401":{"description":"Invalid API key or WordPress application password."},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"No access to the Zernio profile, or the WordPress user lacks required capabilities."},"404":{"description":"Zernio profile not found or WordPress REST endpoint not found."},"502":{"description":"The WordPress site returned an unclassified upstream error."},"503":{"description":"The WordPress site could not be reached."}}}},"/v1/connect/tiktok-ads":{"patch":{"x-resource-group":"accounts","operationId":"configureTikTokAdsBrandIdentity","tags":["Connect"],"summary":"Set TikTok brand identity","description":"Set or update the Brand Identity (display name + avatar) for a `tiktokads` SocialAccount.\n\nTikTok requires every ad to carry an `identity_id + identity_type` pair. The Brand Identity is the CUSTOMIZED_USER alternative to attributing ads to a real @username (TT_USER).\n\n### What this route does\n\n1. Uploads the supplied image to TikTok.\n2. Creates the identity via `/v2/identity/create/`.\n3. Caches the resulting `identity_id` on the account, so subsequent `POST /v1/ads/create` calls can opt into it via `identityType: 'CUSTOMIZED_USER'`.\n\n### Linked accounts\n\nConfigurable on every `tiktokads` account, including linked-mode ones (those with a posting account on the same profile).\n\nConfiguration is idempotent and harmless when posting is also connected. The default ad-create path still prefers TT_USER, and CUSTOMIZED_USER is only used per-ad when the caller explicitly opts in.\n\n### Updating an identity\n\nTikTok identities are immutable post-creation. Re-saving creates a new identity on TikTok and swaps the cached id. The old identity stays orphaned on TikTok's side (harmless, no billing impact).\n\nAlternative: pass `brandIdentity` directly on `POST /v1/ads/create` to configure on first ad creation in a single round-trip.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","displayName","imageUrl"],"properties":{"accountId":{"type":"string","description":"SocialAccount ID of the `tiktokads` account."},"displayName":{"type":"string","minLength":1,"maxLength":40,"description":"Brand name shown above the ad on TikTok."},"imageUrl":{"type":"string","format":"uri","description":"Public URL of a square brand image (≥98×98 px, JPG/PNG, max 5 MB). Used as the brand avatar on the ad."}}}}}},"responses":{"200":{"description":"Brand identity configured (or updated)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"identityId":{"type":"string","description":"The TikTok-assigned identity_id, cached on the account."},"displayName":{"type":"string"}}}}}},"400":{"description":"Missing fields, invalid JSON body, invalid accountId format, invalid lengths, or no advertiser found on the account"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"TikTok Ads account not found"},"500":{"description":"Unexpected server error while caching the identity"},"502":{"description":"TikTok rejected the image upload or the identity creation (type: platform_error; an upstream 4xx status is forwarded instead of 502)"}}}},"/v1/connect/facebook/select-page":{"get":{"x-resource-group":"accounts","operationId":"listFacebookPages","tags":["Connect"],"x-platforms":["facebook","meta"],"summary":"List Facebook pages","description":"Lists the Facebook Pages a user can pick from after signing in, so they can choose which Page to connect.\n\n### Authorization by flow\n\n- Classic connections require profileId and tempToken from the OAuth redirect.\n- Headless connections use X-Connect-Token.\n- The dashboard business-login picker instead sends only selectionToken, an encrypted grant valid for ten minutes. This requires the initiating user and current profile access, and returns only Page IDs and names.\n\nX-Connect-Token cannot authorize business selection.\n","parameters":[{"name":"profileId","in":"query","required":false,"schema":{"type":"string"},"description":"Profile ID from your classic connection flow. Required with tempToken."},{"name":"tempToken","in":"query","required":false,"schema":{"type":"string"},"description":"Temporary Facebook access token from the classic OAuth callback. Required with profileId unless sent in the X-Temp-Token header."},{"name":"X-Temp-Token","in":"header","required":false,"schema":{"type":"string"},"description":"The OAuth user token, in place of the tempToken query parameter. Prefer it: a query string is written to request logs along the way."},{"name":"connectFlow","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-f0-9]{32}$"},"description":"Set by the Zernio-hosted picker, whose user token stays in an httpOnly cookie. Integrators send tempToken instead."},{"name":"selectionToken","in":"query","schema":{"type":"string"},"description":"Encrypted dashboard business-login grant. Send alone instead of profileId and tempToken. Expires after ten minutes.","example":"ENCRYPTED_SELECTION_TOKEN"}],"security":[{"bearerAuth":[]},{"connectToken":[]}],"responses":{"200":{"description":"List of Facebook Pages available for connection","content":{"application/json":{"schema":{"type":"object","properties":{"pages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Facebook Page ID"},"name":{"type":"string","description":"Page name"},"username":{"type":"string","description":"Page username/handle (may be null)"},"access_token":{"type":"string","description":"Page-specific access token"},"category":{"type":"string","description":"Page category"},"tasks":{"type":"array","items":{"type":"string"},"description":"User permissions for this page"}}}},"truncated":{"type":"boolean","description":"True when Meta still had more Pages after the listing hit its time budget or the 10,000 Page cap, so `pages` is incomplete. Do not ask the user to reconnect with fewer Pages ticked: Meta replaces the Page grant on every authorization, so unticked Pages lose access."}}},"example":{"pages":[{"id":"123456789","name":"My Brand Page","username":"mybrand","access_token":"EAAxxxxx...","category":"Brand","tasks":["MANAGE","CREATE_CONTENT"]}],"truncated":false}}}},"400":{"description":"Invalid or expired selectionToken, no granted Pages, or missing classic profileId and tempToken."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The caller is not the initiating user or no longer has profile access."},"429":{"x-summary":"Meta is rate limiting Page reads for this Facebook account: wait the seconds in `Retry-After` and retry.","description":"Meta is rate limiting Page reads for this Facebook account (code `rate_limited`). Retry after `Retry-After` seconds; the listing stops at the first throttle instead of retrying.","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"500":{"description":"Failed to fetch pages (e.g., invalid token, insufficient permissions)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}},"post":{"x-resource-group":"accounts","operationId":"selectFacebookPage","tags":["Connect"],"x-platforms":["facebook","meta"],"summary":"Select Facebook page","description":"Connects the Facebook Page the user picked after signing in, completing the Facebook or Meta Ads connection.\n\n### Two ways to call it\n\n- Classic Facebook Page connection: send profileId, pageId, tempToken and userProfile. Use X-Connect-Token for headless connections.\n- Dashboard business-login picker: send only selectionToken and pageId to complete a Meta Ads connection.\n\n### Business selection\n\nThe server verifies the initiating user, profile access, current grants and connection eligibility. The profile, platform token, ad-account scope and return URL come only from the encrypted grant.\n\nBusiness selection requires a session or bearer authentication for the initiating user; X-Connect-Token is not accepted.\n\nIt returns redirect_url with connected=metaads on success or an eligibility error redirect.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["profileId","userProfile"],"not":{"required":["selectionToken"],"properties":{"selectionToken":{}}},"properties":{"profileId":{"type":"string","description":"Profile ID from your classic connection flow."},"pageId":{"type":"string","description":"The Facebook Page ID selected by the user. Send this or pageIds, not both."},"pageIds":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string"},"description":"Several Page IDs to connect from one sign-in, each as its own account. A single distinct ID behaves exactly like pageId.\n\nWith two or more distinct IDs:\n\n- the response lists `accounts` and `failed` instead of `account`;\n- the request is refused with 400 on a reconnect or an ads connect, which pick exactly one Page.\n"},"tempToken":{"type":"string","description":"Temporary Facebook access token from OAuth. Required unless sent in the X-Temp-Token header."},"connectFlow":{"type":"string","pattern":"^[a-f0-9]{32}$","description":"Set by the Zernio-hosted picker, whose user token stays in an httpOnly cookie. Integrators send tempToken instead."},"userProfile":{"type":"object","description":"Decoded user profile object from the OAuth callback.","properties":{"id":{"type":"string"},"name":{"type":"string"},"profilePicture":{"type":"string"}}},"redirect_url":{"type":"string","format":"uri","description":"Optional custom redirect URL to return to after selection."}}},{"type":"object","additionalProperties":false,"required":["selectionToken","pageId"],"properties":{"selectionToken":{"type":"string","description":"Encrypted dashboard business-login grant. Expires after ten minutes.","example":"ENCRYPTED_SELECTION_TOKEN"},"pageId":{"type":"string","pattern":"^\\d+$","description":"A Page ID from the granted Pages returned by listFacebookPages."}}}]},"example":{"profileId":"507f1f77bcf86cd799439011","pageId":"123456789","tempToken":"EAAxxxxx...","userProfile":{"id":"987654321","username":"john.doe","displayName":"John Doe","profilePicture":"https://...","profileUrl":"https://facebook.com/987654321","bio":null},"redirect_url":"https://yourdomain.com/integrations/callback"}}}},"security":[{"bearerAuth":[]},{"connectToken":[]}],"responses":{"200":{"description":"Facebook Page connected or business-login redirect returned.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"redirect_url":{"type":"string","description":"Redirect URL when a custom redirect_url was provided or a business Page was selected. On an ads connect it also carries `adsAccountId`."},"adsAccountId":{"type":"string","description":"Ads connect only (the redirect_url carries adsConnect=true, as it does after GET /v1/connect/{platform}/ads). The metaads SocialAccount ID to use with the /v1/ads endpoints. `account.accountId` is the Facebook posting account. Absent when the ads account could not be created."},"account":{"type":"object","properties":{"accountId":{"type":"string","description":"ID of the created SocialAccount"},"platform":{"type":"string","enum":["facebook"]},"username":{"type":"string"},"displayName":{"type":"string"},"profilePicture":{"type":"string"},"isActive":{"type":"boolean"},"selectedPageName":{"type":"string"}}},"accounts":{"type":"array","description":"pageIds only. The connected accounts, same shape as `account`. The redirect_url then carries `accountIds` (comma-separated) and `accountId` of the first.","items":{"type":"object"}},"failed":{"type":"array","description":"pageIds only. The Pages that could not be connected while the others were.","items":{"type":"object","properties":{"id":{"type":"string","description":"The Page ID."},"code":{"type":"string"},"message":{"type":"string"}}}}}},"example":{"message":"Facebook page connected successfully","redirect_url":"https://yourdomain.com/integrations/callback?connected=facebook&profileId=507f1f77bcf86cd799439011&accountId=64e1f0a9e2b5af0012ab34cd&username=My+Brand+Page","account":{"accountId":"64e1f0a9e2b5af0012ab34cd","platform":"facebook","username":"mybrand","displayName":"My Brand Page","profilePicture":"https://...","isActive":true,"selectedPageName":"My Brand Page"}}}}},"400":{"description":"Invalid or expired selectionToken, invalid Page choice, forbidden grant overrides, or missing classic connection fields."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"User does not have access to the specified profile"},"404":{"description":"Selected page not found in available pages"},"409":{"x-summary":"The authorization landed on a different Facebook user or page than the connected account, so nothing changed: reconnect with the original account.","description":"Reconnect identity mismatch. The OAuth was initiated as a `force=true` token-recovery re-auth (`GET /v1/connect/{platform}/ads`), but the grant landed on a different Facebook user or page than the connected account. The existing account is left untouched.\n\nReturned in the standard error envelope with `code: reconnect_account_mismatch` (the same value the OAuth redirect uses in `error=`). Before 1.79.0 this body was `{error, code: RECONNECT_ACCOUNT_MISMATCH}` without `type`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"x-summary":"None of the selected Pages could be connected: read `details.failed` for each reason and fix them.","description":"pageIds only. None of the Pages could be connected; `details.failed` lists each one with its reason.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"x-summary":"Meta is rate limiting Page reads for this Facebook account: wait the seconds in `Retry-After` and retry.","description":"Meta is rate limiting Page reads for this Facebook account (code `rate_limited`). Retry after `Retry-After` seconds; the listing stops at the first throttle instead of retrying.","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"500":{"description":"Failed to save Facebook connection"}}}},"/v1/connect/instagram/select-account":{"get":{"x-resource-group":"accounts","operationId":"listInstagramPages","tags":["Connect"],"summary":"List Pages with a linked Instagram account","description":"Completes the `loginMethod=facebook_login` Instagram flow, i.e. \"Instagram API with Facebook Login\".\n\n### Flow\n\n1. The user authorizes on Facebook.\n2. Extract `tempToken` from the redirect params (headless mode adds `step=select_account`).\n3. Pass it here to list the Facebook Pages they manage.\n\nOnly Pages that have a linked Instagram professional account are returned, so an empty array means the user has no eligible Page. Use the X-Connect-Token header if connecting via API key.\n\nNot used by the default `instagram_login` flow, which creates the account without a selection step.\n","parameters":[{"name":"profileId","in":"query","required":true,"schema":{"type":"string"},"description":"Profile ID from your connection flow"},{"name":"tempToken","in":"query","required":false,"schema":{"type":"string"},"description":"Long-lived Facebook user access token from the OAuth callback redirect. Required unless sent in the X-Temp-Token header."},{"name":"X-Temp-Token","in":"header","required":false,"schema":{"type":"string"},"description":"The OAuth user token, in place of the tempToken query parameter. Prefer it: a query string is written to request logs along the way."},{"name":"connectFlow","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-f0-9]{32}$"},"description":"Set by the Zernio-hosted picker, whose user token stays in an httpOnly cookie. Integrators send tempToken instead."}],"security":[{"bearerAuth":[]},{"connectToken":[]}],"responses":{"200":{"description":"Facebook Pages that have a linked Instagram professional account","content":{"application/json":{"schema":{"type":"object","properties":{"pages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Facebook Page ID"},"name":{"type":"string","description":"Page name"},"access_token":{"type":"string","description":"Page-specific access token"},"instagram_business_account":{"type":"object","description":"The Instagram professional account linked to this Page","properties":{"id":{"type":"string","description":"Instagram Business Account ID"},"username":{"type":"string"},"profile_picture_url":{"type":"string"},"followers_count":{"type":"integer","description":"Followers of the Instagram account when Meta returns it"}}}}}}}},"example":{"pages":[{"id":"811889972008357","name":"My Brand Page","access_token":"EAAxxxxx...","instagram_business_account":{"id":"17841400649984407","username":"mybrand","profile_picture_url":"https://..."}}]}}}},"400":{"description":"Missing required parameters (profileId or tempToken)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"User does not have access to the specified profile"},"429":{"x-summary":"Meta is rate limiting Page reads for this Facebook account: wait the seconds in `Retry-After` and retry.","description":"Meta is rate limiting Page reads for this Facebook account (code `rate_limited`). Retry after `Retry-After` seconds; the listing stops at the first throttle instead of retrying.","headers":{"Retry-After":{"schema":{"type":"integer"}}}}}},"post":{"x-resource-group":"accounts","operationId":"selectInstagramAccount","tags":["Connect"],"summary":"Select the Page whose Instagram account to connect","description":"Saves the selected Page as an Instagram account connected via Facebook Login. The Page access token becomes the account's access token, so every Instagram call for it runs against the Facebook Graph host.\n\nA different Instagram account is added next to any already connected on the profile; picking one already connected refreshes it.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId"],"properties":{"profileId":{"type":"string","description":"Profile ID from your connection flow"},"pageId":{"type":"string","description":"The Facebook Page ID selected by the user, from GET /v1/connect/instagram/select-account. Send this or pageIds, not both."},"pageIds":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string"},"description":"Several Page IDs whose linked Instagram accounts to connect from one sign-in, each as its own account.\n\n- Two or more distinct IDs: the response lists `accounts` and `failed` instead of `account`. Refused with 400 on a reconnect or an ads connect.\n- A single distinct ID behaves exactly like pageId.\n"},"tempToken":{"type":"string","description":"Long-lived Facebook user access token from the OAuth callback redirect. Required unless sent in the X-Temp-Token header."},"connectFlow":{"type":"string","pattern":"^[a-f0-9]{32}$","description":"Set by the Zernio-hosted picker, whose user token stays in an httpOnly cookie. Integrators send tempToken instead."},"redirect_url":{"type":"string","format":"uri","description":"Optional custom redirect URL to return to after selection"}}},"example":{"profileId":"507f1f77bcf86cd799439011","pageId":"811889972008357","tempToken":"EAAxxxxx...","redirect_url":"https://yourdomain.com/integrations/callback"}}}},"security":[{"bearerAuth":[]},{"connectToken":[]}],"responses":{"200":{"description":"Instagram account connected","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"redirect_url":{"type":"string","description":"Redirect URL if a custom redirect_url was provided. On an ads connect it also carries `adsAccountId`."},"adsAccountId":{"type":"string","description":"Ads connect only (the redirect_url carries adsConnect=true, as it does after GET /v1/connect/{platform}/ads). The metaads SocialAccount ID to use with the /v1/ads endpoints. `account.accountId` is the Instagram posting account. Absent when the ads account could not be created."},"account":{"type":"object","properties":{"accountId":{"type":"string","description":"ID of the created SocialAccount"},"platform":{"type":"string","enum":["instagram"]},"username":{"type":"string"},"displayName":{"type":"string","description":"Name of the Facebook Page backing this account"},"profilePicture":{"type":"string"},"isActive":{"type":"boolean"},"loginMethod":{"type":"string","enum":["facebook_login"]}}},"accounts":{"type":"array","description":"pageIds only. The connected accounts, same shape as `account`. The redirect_url then carries `accountIds` (comma-separated) and `accountId` of the first.","items":{"type":"object"}},"failed":{"type":"array","description":"pageIds only. The Pages whose Instagram account could not be connected while the others were.","items":{"type":"object","properties":{"id":{"type":"string","description":"The Page ID."},"code":{"type":"string"},"message":{"type":"string"}}}}}},"example":{"message":"Instagram (via Facebook) connected","account":{"accountId":"64e1f0a9e2b5af0012ab34cd","platform":"instagram","username":"mybrand","displayName":"My Brand Page","profilePicture":"https://...","isActive":true,"loginMethod":"facebook_login"}}}}},"400":{"description":"Missing required fields, or the selected Page has no linked Instagram professional account"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"User does not have access to the specified profile"},"404":{"description":"Selected page not found among the pages this token can manage"},"409":{"x-summary":"Nothing was written: the selected Instagram account is not the one the connect was started for, or an Instagram Login account on the profile whose access expired cannot be confirmed as the same account.","description":"Nothing is written. Standard error envelope, with one of these codes:\n\n- `account_mismatch`: the connect was started with `expectedPlatformUserId` or `expectedUsername` (carried on redirect_url) and the selected Page's Instagram account is not that account. With pageIds the mismatching Pages are listed in `failed` instead.\n- `instagram_identity_unconfirmed`: the profile holds an Instagram account connected with Instagram Login whose access expired, so Zernio cannot confirm whether it is the account being connected through Facebook. Reconnect it with Instagram Login or disconnect it, then retry.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"x-summary":"None of the selected accounts could be connected: read `details.failed` for each reason and fix them.","description":"pageIds only. None of the accounts could be connected; `details.failed` lists each Page with its reason.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"x-summary":"Meta is rate limiting Page reads for this Facebook account: wait the seconds in `Retry-After` and retry.","description":"Meta is rate limiting Page reads for this Facebook account (code `rate_limited`). Retry after `Retry-After` seconds; the listing stops at the first throttle instead of retrying.","headers":{"Retry-After":{"schema":{"type":"integer"}}}}}}},"/v1/connect/googlebusiness/locations":{"get":{"x-resource-group":"accounts","operationId":"listGoogleBusinessLocations","tags":["Connect"],"summary":"List Google Business Profile locations","description":"For headless flows. Returns the list of Google Business Profile locations the user can manage. Use pendingDataToken (from the OAuth callback redirect) to list locations without consuming the token, so it remains available for select-location. Use X-Connect-Token header if connecting via API key.\n","parameters":[{"name":"profileId","in":"query","required":false,"schema":{"type":"string"},"description":"Profile ID from your connection flow. Required for auth validation when provided."},{"name":"pendingDataToken","in":"query","required":false,"schema":{"type":"string"},"description":"Token from the OAuth callback redirect. Preferred over tempToken because it preserves server-side token storage. One of pendingDataToken or tempToken is required."},{"name":"tempToken","in":"query","required":false,"schema":{"type":"string"},"description":"Legacy. Direct Google access token. Use pendingDataToken instead when available."},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Free-text search on the business name, applied server-side by Google. Use this for accounts that own many locations (the response is bounded, see hasMore) so the user can find a specific location without loading the full list.\n"},{"name":"filter","in":"query","required":false,"schema":{"type":"string"},"description":"Raw Google Business Information API filter expression (advanced; takes precedence over search). Supports fields such as title, storeCode, storefront_address.postal_code, labels and categories, e.g. storeCode=\"LH279411\". See Google's \"Work with location data\" guide.\n"}],"security":[{"bearerAuth":[]},{"connectToken":[]}],"responses":{"200":{"description":"List of Google Business Profile locations available for connection","content":{"application/json":{"schema":{"type":"object","properties":{"locations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Location ID"},"name":{"type":"string","description":"Business name"},"accountId":{"type":"string","description":"Google Business Profile Account ID"},"accountName":{"type":"string","description":"Account name"},"address":{"type":"string","description":"Business address"},"category":{"type":"string","description":"Business category"},"storeCode":{"type":"string","description":"Store code set on the location in Google Business Profile (if any)"}}}},"hasMore":{"type":"boolean","description":"True when more locations exist than were returned (the list is bounded). Prompt the user to narrow the result set with search.\n"}}},"example":{"locations":[{"id":"9281089117903930794","name":"My Coffee Shop","accountId":"accounts/113303573364907650416","accountName":"My Business Account","address":"123 Main St, City, Country","category":"Coffee shop","storeCode":"CS-001"}],"hasMore":false}}}},"400":{"description":"Missing required parameters (profileId or tempToken)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The connect token was issued for a different profile or platform (INSUFFICIENT_PERMISSIONS)."},"500":{"description":"Failed to fetch locations (e.g., invalid token, insufficient permissions)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/v1/connect/googlebusiness/select-location":{"post":{"x-resource-group":"accounts","operationId":"selectGoogleBusinessLocation","tags":["Connect"],"summary":"Select Google Business Profile location","description":"Complete the headless Google Business Profile flow by saving the user's selected location. The pendingDataToken is returned in your redirect URL after OAuth completes (step=select_location). Tokens and profile data are stored server-side, so only the pendingDataToken is needed here. Use X-Connect-Token header if connecting via API key.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","pendingDataToken"],"properties":{"profileId":{"type":"string","description":"Profile ID from your connection flow"},"locationId":{"type":"string","description":"The Google Business Profile location ID selected by the user. Send this or locations, not both."},"locations":{"type":"array","minItems":1,"maxItems":25,"description":"Several locations to connect from one sign-in, each as its own account. A single location behaves exactly like locationId.\n\nThe sign-in is used once for the whole batch and handed back only if none connected. With two or more distinct locations, the response lists `accounts` and `failed` instead of `account`, and the request is refused with 400 on a reconnect.\n","items":{"type":"object","required":["locationId"],"properties":{"locationId":{"type":"string"},"accountId":{"type":"string","description":"The location's Google Business Profile Account resource name, as for the top-level accountId."}}}},"accountId":{"type":"string","description":"Optional but recommended. The Google Business Profile Account resource name (\"accounts/123\") that owns the selected location (returned per-location by GET /v1/connect/googlebusiness/locations). When provided, the location is resolved directly instead of by enumerating the account, which is required for accounts that own many locations. Omit only for small accounts.\n"},"pendingDataToken":{"type":"string","description":"Token from the OAuth callback redirect (pendingDataToken query param). Tokens and profile data are retrieved server-side from this token."},"redirect_url":{"type":"string","format":"uri","description":"Optional custom redirect URL to return to after selection"}}},"example":{"profileId":"507f1f77bcf86cd799439011","locationId":"9281089117903930794","accountId":"accounts/113303573364907650416","pendingDataToken":"a1b2c3d4e5f6...","redirect_url":"https://yourdomain.com/integrations/callback"}}}},"security":[{"bearerAuth":[]},{"connectToken":[]}],"responses":{"200":{"description":"Google Business Profile location connected successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"redirect_url":{"type":"string","description":"Redirect URL if custom redirect_url was provided"},"account":{"type":"object","properties":{"accountId":{"type":"string","description":"ID of the created SocialAccount"},"platform":{"type":"string","enum":["googlebusiness"]},"username":{"type":"string"},"displayName":{"type":"string"},"isActive":{"type":"boolean"},"selectedLocationName":{"type":"string","description":"Human-readable location display name, NOT a resource name. Do not use it to build API paths."},"selectedLocationId":{"type":"string","description":"Bare Google Business Profile location id. Combine with the Google Business Profile account id as accounts/{gbpAccountId}/locations/{selectedLocationId} to form the location resource names that gmb-reviews/batch expects in locationNames."}}},"accounts":{"type":"array","description":"locations with two or more distinct entries only. The connected accounts, same shape as `account`. The redirect_url then carries `accountIds` (comma-separated) and `accountId` of the first.","items":{"type":"object"}},"failed":{"type":"array","description":"locations only. The locations that could not be connected while the others were.","items":{"type":"object","properties":{"id":{"type":"string","description":"The location ID."},"code":{"type":"string"},"message":{"type":"string"}}}}}},"example":{"message":"Google Business location connected successfully","redirect_url":"https://yourdomain.com/integrations/callback?connected=googlebusiness&profileId=507f1f77bcf86cd799439011&accountId=64e1f0a9e2b5af0012ab34cd&username=My+Coffee+Shop","account":{"accountId":"64e1f0a9e2b5af0012ab34cd","platform":"googlebusiness","username":"My Coffee Shop","displayName":"My Coffee Shop","isActive":true,"selectedLocationName":"My Coffee Shop","selectedLocationId":"9281089117903930794"}}}}},"400":{"description":"Missing required fields (profileId, locationId, or tempToken), or the provided accountId is not one of the accounts this connection manages"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"User does not have access to the specified profile"},"404":{"description":"Selected location not found in available locations"},"422":{"x-summary":"None of the selected locations could be connected: read `details.failed` for each reason and fix them.","description":"locations only. None of the locations could be connected; `details.failed` lists each one with its reason.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to save Google Business Profile connection"}}}},"/v1/accounts/{accountId}/gmb-reviews":{"get":{"x-resource-group":"engagement","operationId":"getGoogleBusinessReviews","tags":["GMB Reviews"],"summary":"Get reviews","description":"Returns reviews for a Google Business Profile account including ratings, comments, and owner replies. Use nextPageToken for pagination.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"The Zernio account ID (from /v1/accounts)"},{"name":"locationId","in":"query","schema":{"type":"string"},"description":"Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs."},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":50},"description":"Number of reviews to fetch per page (max 50)"},{"name":"pageToken","in":"query","schema":{"type":"string"},"description":"Pagination token from previous response"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Reviews fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"locationId":{"type":"string"},"reviews":{"type":"array","items":{"$ref":"#/components/schemas/GoogleBusinessReview"}},"averageRating":{"type":"number","description":"Overall average rating"},"totalReviewCount":{"type":"integer","description":"Total number of reviews"},"nextPageToken":{"type":["string","null"],"description":"Token for next page"}}},"example":{"success":true,"accountId":"64e1f0a9e2b5af0012ab34cd","locationId":"9281089117903930794","reviews":[{"id":"AIe9_BGx1234567890","name":"accounts/123456789/locations/9281089117903930794/reviews/AIe9_BGx1234567890","reviewer":{"displayName":"John Smith","profilePhotoUrl":"https://lh3.googleusercontent.com/a/...","isAnonymous":false},"rating":5,"starRating":"FIVE","comment":"Great service and friendly staff! Highly recommend.","createTime":"2024-01-15T10:30:00Z","updateTime":"2024-01-15T10:30:00Z","reviewReply":{"comment":"Thank you for your kind words! We appreciate your support.","updateTime":"2024-01-16T08:00:00Z"},"photoCount":0,"photos":[]},{"id":"AIe9_BGx0987654321","name":"accounts/123456789/locations/9281089117903930794/reviews/AIe9_BGx0987654321","reviewer":{"displayName":"Anonymous","profilePhotoUrl":null,"isAnonymous":true},"rating":4,"starRating":"FOUR","comment":"Good experience overall.","createTime":"2024-01-10T14:20:00Z","updateTime":"2024-01-10T14:20:00Z","reviewReply":null,"photoCount":0,"photos":[]}],"averageRating":4.5,"totalReviewCount":125,"nextPageToken":"CiAKHAoUMTIzNDU2Nzg5"}}}},"400":{"description":"Invalid request - not a Google Business Profile account or missing location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"This endpoint is only available for Google Business Profile accounts"}}}},"401":{"description":"Unauthorized or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Access token invalid. Please reconnect your Google Business Profile account.","code":"token_invalid"}}}},"403":{"description":"Permission denied for this location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"You do not have permission to access reviews for this location."}}}},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"Failed to fetch reviews","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"$ref":"#/components/responses/UpstreamFailure"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/v1/accounts/{accountId}/gmb-verifications":{"get":{"x-resource-group":"accounts","operationId":"getGoogleBusinessVerifications","tags":["GMB Verifications"],"summary":"Get verification state","description":"Returns the location's Voice of Merchant state plus its verification history. `voiceOfMerchantState.hasVoiceOfMerchant` tells you whether the listing is verified and published; when it is false, `verify` reports whether a verification is already pending. Each entry in `verifications` has a `state` of PENDING, COMPLETED, or FAILED.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"The Zernio account ID (from /v1/accounts)"},{"name":"locationId","in":"query","schema":{"type":"string"},"description":"Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Verification state fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"locationId":{"type":"string"},"voiceOfMerchantState":{"type":"object","description":"Raw Voice of Merchant state from Google.","properties":{"hasVoiceOfMerchant":{"type":"boolean","description":"True when the listing is verified and published (eligible to surface reviews, edits, etc.)."},"hasBusinessAuthority":{"type":"boolean","description":"True when the authenticated user has owner/manager authority over the listing."},"verify":{"type":"object","description":"Present when verification is the path to Voice of Merchant.","properties":{"hasPendingVerification":{"type":"boolean","description":"True when a verification is already in progress."}}}}},"verifications":{"type":"array","description":"Verification history, newest first. Empty when none exist.","items":{"type":"object","properties":{"name":{"type":"string","description":"Resource name, e.g. \"locations/123/verifications/0T1776879124712\". The last segment is the verificationId."},"method":{"type":"string","enum":["ADDRESS","EMAIL","PHONE_CALL","SMS","AUTO","VETTED_PARTNER"],"description":"Method used (omitted on some entries)."},"state":{"type":"string","enum":["PENDING","COMPLETED","FAILED"]},"createTime":{"type":"string","format":"date-time"}}}}}},"example":{"success":true,"accountId":"64e1f0a9e2b5af0012ab34cd","locationId":"16699729527667179850","voiceOfMerchantState":{"hasVoiceOfMerchant":false,"hasBusinessAuthority":true,"verify":{"hasPendingVerification":false}},"verifications":[{"name":"locations/16699729527667179850/verifications/4T1775504407480","method":"SMS","state":"FAILED","createTime":"2026-04-06T19:40:07.480Z"}]}}}},"400":{"description":"Not a Google Business Profile account or missing location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"x-resource-group":"accounts","operationId":"startGoogleBusinessVerification","tags":["GMB Verifications"],"summary":"Start a verification","description":"Starts a verification for the location. This is a mutating action: depending on `method`, Google mails a postcard, places a call, or sends an SMS/email to the business. Submit the resulting code with POST /gmb-verifications/{verificationId}/complete. Use POST /gmb-verifications/options first to discover which methods are eligible.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"The Zernio account ID (from /v1/accounts)"},{"name":"locationId","in":"query","schema":{"type":"string"},"description":"Override which location to target. If omitted, uses the account's selected location."}],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["method"],"properties":{"method":{"type":"string","enum":["ADDRESS","EMAIL","PHONE_CALL","SMS","AUTO","VETTED_PARTNER"],"description":"The verification method. Selects which method-specific field below is required."},"languageCode":{"type":"string","example":"en-US"},"phoneNumber":{"type":"string","description":"For PHONE_CALL / SMS."},"emailAddress":{"type":"string","description":"For EMAIL."},"mailerContact":{"type":"object","description":"For ADDRESS (postcard) verification."},"context":{"type":"object","description":"ServiceBusinessContext (e.g. service address). Required for service-area businesses."}}},"example":{"method":"SMS","languageCode":"en-US","phoneNumber":"+14155550123"}}}},"responses":{"200":{"description":"Verification started","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"locationId":{"type":"string"},"verification":{"type":"object","properties":{"name":{"type":"string"},"method":{"type":"string","enum":["ADDRESS","EMAIL","PHONE_CALL","SMS","AUTO","VETTED_PARTNER"]},"state":{"type":"string","enum":["PENDING","COMPLETED","FAILED"]},"createTime":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Invalid request (e.g. wrong field for the chosen method, or Google rejected it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/accounts/{accountId}/gmb-verifications/options":{"post":{"x-resource-group":"accounts","operationId":"fetchGoogleBusinessVerificationOptions","tags":["GMB Verifications"],"summary":"Fetch verification options","description":"Reports the verification methods Google currently offers for the location. Non-mutating (nothing is sent to the business). `languageCode` is required; service-area (\"CUSTOMER_LOCATION_ONLY\") businesses also require `context.address`, otherwise Google returns 400.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"The Zernio account ID (from /v1/accounts)"},{"name":"locationId","in":"query","schema":{"type":"string","minLength":1},"description":"Override which location to query. If omitted, uses the account's selected location."}],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["languageCode"],"properties":{"languageCode":{"type":"string","example":"en-US"},"context":{"type":"object","description":"ServiceBusinessContext. Required for service-area businesses (must include the service address)."}}},"example":{"languageCode":"en-US"}}}},"responses":{"200":{"description":"Verification options fetched","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"locationId":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"verificationMethod":{"type":"string","enum":["ADDRESS","EMAIL","PHONE_CALL","SMS","AUTO","VETTED_PARTNER"]},"phoneNumber":{"type":"string","description":"Present for PHONE_CALL / SMS."}}}}}}}}},"400":{"description":"Invalid request (e.g. missing service business context, or missing languageCode)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/accounts/{accountId}/gmb-verifications/{verificationId}/complete":{"post":{"x-resource-group":"accounts","operationId":"completeGoogleBusinessVerification","tags":["GMB Verifications"],"summary":"Complete a verification","description":"Completes a PENDING verification by submitting the PIN/code Google sent the business (postcard code, SMS PIN, etc.). On success the verification moves to COMPLETED.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"The Zernio account ID (from /v1/accounts)"},{"name":"verificationId","in":"path","required":true,"schema":{"type":"string"},"description":"The last segment of a verification `name` from GET /gmb-verifications."},{"name":"locationId","in":"query","schema":{"type":"string","minLength":1},"description":"Override which location to target. If omitted, uses the account's selected location."}],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pin"],"properties":{"pin":{"type":"string","description":"The code Google sent to the business."}}},"example":{"pin":"123456"}}}},"responses":{"200":{"description":"Verification completed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"locationId":{"type":"string"},"verification":{"type":"object","properties":{"name":{"type":"string"},"method":{"type":"string","enum":["ADDRESS","EMAIL","PHONE_CALL","SMS","AUTO","VETTED_PARTNER"]},"state":{"type":"string","enum":["PENDING","COMPLETED","FAILED"]},"createTime":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Invalid request (e.g. wrong PIN or verification not pending)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/accounts/{accountId}/gmb-food-menus":{"get":{"x-resource-group":"accounts","operationId":"getGoogleBusinessFoodMenus","tags":["GMB Food Menus"],"summary":"Get food menus","description":"Returns food menus for a Google Business Profile location including sections, items, pricing, and dietary info. Only for locations with food menu support.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"The Zernio account ID (from /v1/accounts)"},{"name":"locationId","in":"query","schema":{"type":"string"},"description":"Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Food menus fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"locationId":{"type":"string"},"name":{"type":"string","description":"Resource name of the food menus"},"menus":{"type":"array","items":{"$ref":"#/components/schemas/FoodMenu"}}}},"example":{"success":true,"accountId":"64e1f0a9e2b5af0012ab34cd","locationId":"9281089117903930794","name":"accounts/123456789/locations/9281089117903930794/foodMenus","menus":[{"labels":[{"displayName":"Lunch Menu","description":"Available 11am-3pm","languageCode":"en"}],"sections":[{"labels":[{"displayName":"Appetizers"}],"items":[{"labels":[{"displayName":"Caesar Salad","description":"Romaine, parmesan, croutons"}],"attributes":{"price":{"currencyCode":"USD","units":"12"},"dietaryRestriction":["VEGETARIAN"]}}]}]}]}}}},"400":{"description":"Invalid request - not a Google Business Profile account or missing location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"This endpoint is only available for Google Business Profile accounts"}}}},"401":{"description":"Unauthorized or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Access token invalid. Please reconnect your Google Business Profile account.","code":"token_invalid"}}}},"403":{"description":"Permission denied for this location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"You do not have permission to access food menus for this location."}}}},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"Failed to fetch food menus","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"x-resource-group":"accounts","operationId":"updateGoogleBusinessFoodMenus","tags":["GMB Food Menus"],"summary":"Update food menus","description":"Updates food menus for a Google Business Profile location. Send the full menus array. Use updateMask for partial updates.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"The Zernio account ID (from /v1/accounts)"},{"name":"locationId","in":"query","schema":{"type":"string"},"description":"Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs."}],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["menus"],"properties":{"menus":{"type":"array","items":{"$ref":"#/components/schemas/FoodMenu"},"description":"Array of food menus to set"},"updateMask":{"type":"string","description":"Field mask for partial updates (e.g. \"menus\")"}}},"example":{"menus":[{"labels":[{"displayName":"Dinner Menu","languageCode":"en"}],"sections":[{"labels":[{"displayName":"Mains"}],"items":[{"labels":[{"displayName":"Grilled Salmon","description":"With seasonal vegetables"}],"attributes":{"price":{"currencyCode":"USD","units":"24"},"allergen":["FISH"]}}]}]}],"updateMask":"menus"}}}},"responses":{"200":{"description":"Food menus updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"locationId":{"type":"string"},"name":{"type":"string"},"menus":{"type":"array","items":{"$ref":"#/components/schemas/FoodMenu"}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Request body must include a \"menus\" array"}}}},"401":{"description":"Unauthorized or token expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Permission denied for this location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"Failed to update food menus","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/accounts/{accountId}/gmb-location-details":{"get":{"x-resource-group":"accounts","operationId":"getGoogleBusinessLocationDetails","tags":["GMB Location Details"],"summary":"Get location details","description":"Returns detailed Google Business Profile location info (hours, description, phone, website, categories, services). Use readMask to request specific fields.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"The Zernio account ID (from /v1/accounts)"},{"name":"locationId","in":"query","schema":{"type":"string"},"description":"Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs."},{"name":"readMask","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated fields to return. Available: name, title, phoneNumbers, categories, storefrontAddress, websiteUri, regularHours, specialHours, serviceArea, serviceItems, profile, openInfo, metadata, moreHours.\n\n`title` and `metadata` are always included in the response so the `location` summary block can be populated, even if you omit them here.\n\n`location` is a derived response field, not a Google readMask value: passing it returns 400.\n"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Location details fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"locationId":{"type":"string"},"location":{"type":["object","null"],"description":"Compact public-facing summary derived from Google's `metadata`. Useful\nfor surfacing the \"leave a review\" URL (e.g. behind a QR code) without\nparsing the raw block. Always populated regardless of readMask.\nFor unverified or new locations Google omits placeId/reviewUrl/mapsUri,\nso those return as null and `isVerified` is false.\n","properties":{"name":{"type":["string","null"],"description":"Business name as set in Google Business Profile"},"placeId":{"type":["string","null"],"description":"Google Maps Place ID for this location"},"reviewUrl":{"type":["string","null"],"description":"Public \"write a review\" URL Google generates for this place"},"mapsUri":{"type":["string","null"],"description":"Public Google Maps URL for this location"},"isVerified":{"type":"boolean","description":"True when the location has Voice of Merchant (verified + live on Google)"}}},"title":{"type":"string","description":"Business name"},"regularHours":{"type":"object","properties":{"periods":{"type":"array","items":{"type":"object","properties":{"openDay":{"type":"string","enum":["MONDAY","TUESDAY","WEDNESDAY","THURSDAY","FRIDAY","SATURDAY","SUNDAY"]},"openTime":{"type":"string","description":"Opening time in HH:MM format"},"closeDay":{"type":"string"},"closeTime":{"type":"string"}}}}}},"specialHours":{"type":"object","properties":{"specialHourPeriods":{"type":"array","items":{"type":"object","properties":{"startDate":{"type":"object","properties":{"year":{"type":"integer"},"month":{"type":"integer"},"day":{"type":"integer"}}},"endDate":{"type":"object","properties":{"year":{"type":"integer"},"month":{"type":"integer"},"day":{"type":"integer"}}},"openTime":{"type":"string"},"closeTime":{"type":"string"},"closed":{"type":"boolean"}}}}}},"profile":{"type":"object","properties":{"description":{"type":"string","description":"Business description"}}},"websiteUri":{"type":"string"},"phoneNumbers":{"type":"object","properties":{"primaryPhone":{"type":"string"},"additionalPhones":{"type":"array","items":{"type":"string"}}}},"categories":{"type":"object","description":"Business categories (returned when readMask includes 'categories')","properties":{"primaryCategory":{"type":"object","properties":{"name":{"type":"string","description":"Category resource name"},"displayName":{"type":"string","description":"Human-readable category name"}}},"additionalCategories":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"displayName":{"type":"string"}}}}}},"serviceItems":{"type":"array","description":"Services offered (returned when readMask includes 'serviceItems')","items":{"type":"object","properties":{"structuredServiceItem":{"type":"object","properties":{"serviceTypeId":{"type":"string"},"description":{"type":"string"}}},"freeFormServiceItem":{"type":"object","properties":{"category":{"type":"string"},"label":{"type":"object","properties":{"displayName":{"type":"string"},"languageCode":{"type":"string"}}}}},"price":{"type":"object","properties":{"currencyCode":{"type":"string"},"units":{"type":"string"},"nanos":{"type":"integer"}}}}}}}},"example":{"success":true,"accountId":"64e1f0a9e2b5af0012ab34cd","locationId":"9281089117903930794","location":{"name":"Joe's Pizza","placeId":"ChIJExampleJoesPizzaPlaceId","reviewUrl":"https://search.google.com/local/writereview?placeid=ChIJExampleJoesPizzaPlaceId","mapsUri":"https://maps.google.com/maps?cid=1234567890123456789","isVerified":true},"title":"Joe's Pizza","regularHours":{"periods":[{"openDay":"MONDAY","openTime":"11:00","closeDay":"MONDAY","closeTime":"22:00"},{"openDay":"TUESDAY","openTime":"11:00","closeDay":"TUESDAY","closeTime":"22:00"}]},"specialHours":{"specialHourPeriods":[{"startDate":{"year":2026,"month":12,"day":25},"closed":true}]},"profile":{"description":"Authentic New York style pizza since 1985"},"websiteUri":"https://joespizza.com","categories":{"primaryCategory":{"name":"categories/gcid:pizza_restaurant","displayName":"Pizza restaurant"},"additionalCategories":[{"name":"categories/gcid:italian_restaurant","displayName":"Italian restaurant"}]}}}}},"400":{"x-summary":"The request is invalid, most commonly because the read mask includes a field Google Business Information does not accept: fix the mask.","description":"Invalid request. Most commonly raised when the readMask query\nincludes a value that is not a valid Google Business Information\nfield (e.g. `location`, which is a response-only derived field).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Request contains an invalid argument.","code":"gbp_bad_request"}}}},"401":{"description":"Unauthorized or token expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"x-resource-group":"accounts","operationId":"updateGoogleBusinessLocationDetails","tags":["GMB Location Details"],"summary":"Update location details","description":"Updates Google Business Profile location details. The updateMask field is required and specifies which fields to update.\nThis endpoint proxies Google's Business Information API locations.patch, so any valid updateMask field is supported.\nCommon fields: regularHours, specialHours, profile.description, websiteUri, phoneNumbers, categories, serviceItems.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"The Zernio account ID (from /v1/accounts)"},{"name":"locationId","in":"query","schema":{"type":"string"},"description":"Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs."}],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["updateMask"],"additionalProperties":true,"properties":{"updateMask":{"type":"string","description":"Required. Comma-separated fields to update (e.g. 'regularHours', 'specialHours', 'profile.description', 'categories', 'serviceItems'). Any valid Google Business Information API updateMask field is supported."},"regularHours":{"type":"object","properties":{"periods":{"type":"array","items":{"type":"object","properties":{"openDay":{"type":"string"},"openTime":{"type":"string"},"closeDay":{"type":"string"},"closeTime":{"type":"string"}}}}}},"specialHours":{"type":"object","properties":{"specialHourPeriods":{"type":"array","items":{"type":"object","properties":{"startDate":{"type":"object","properties":{"year":{"type":"integer"},"month":{"type":"integer"},"day":{"type":"integer"}}},"endDate":{"type":"object","properties":{"year":{"type":"integer"},"month":{"type":"integer"},"day":{"type":"integer"}}},"openTime":{"type":"string"},"closeTime":{"type":"string"},"closed":{"type":"boolean"}}}}}},"profile":{"type":"object","properties":{"description":{"type":"string"}}},"websiteUri":{"type":"string"},"phoneNumbers":{"type":"object","properties":{"primaryPhone":{"type":"string"},"additionalPhones":{"type":"array","items":{"type":"string"}}}},"categories":{"type":"object","description":"Primary and additional business categories. Use updateMask='categories' to update.","properties":{"primaryCategory":{"type":"object","properties":{"name":{"type":"string","description":"Category resource name (e.g. 'categories/gcid:laundromat'). Use Google's Categories API to look up valid IDs."}}},"additionalCategories":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Category resource name (e.g. 'categories/gcid:dry_cleaner')"}}}}}},"serviceItems":{"type":"array","description":"Services offered by the business. Use updateMask='serviceItems' to update.","items":{"type":"object","properties":{"structuredServiceItem":{"type":"object","description":"A predefined service from Google's service type catalog","properties":{"serviceTypeId":{"type":"string","description":"Service type ID from Google's catalog (e.g. 'job_type_id:plumbing_drain_repair')"},"description":{"type":"string","description":"Optional description of the service"}}},"freeFormServiceItem":{"type":"object","description":"A custom service not in Google's catalog","properties":{"category":{"type":"string","description":"Category resource name this service belongs to (e.g. 'categories/gcid:laundromat')"},"label":{"type":"object","properties":{"displayName":{"type":"string","description":"Service name as displayed to users"},"languageCode":{"type":"string","description":"Language code (e.g. 'en')"}}}}},"price":{"type":"object","description":"Optional price for the service","properties":{"currencyCode":{"type":"string","description":"ISO 4217 currency code (e.g. 'USD')"},"units":{"type":"string","description":"Whole units of the amount"},"nanos":{"type":"integer","description":"Nano units (10^-9) of the amount"}}}}}},"title":{"type":"string","description":"Business name. Use updateMask='title'."},"storeCode":{"type":"string","description":"External store identifier, unique within the account. Use updateMask='storeCode'."},"labels":{"type":"array","description":"Free-form, internal-only labels for grouping (1-255 characters each). Use updateMask='labels'.","items":{"type":"string"}},"storefrontAddress":{"type":"object","description":"Postal address of the storefront. Use updateMask='storefrontAddress'. Omit for service-area-only businesses.","properties":{"regionCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code (e.g. 'BR')"},"languageCode":{"type":"string"},"postalCode":{"type":"string"},"administrativeArea":{"type":"string","description":"State or province"},"locality":{"type":"string","description":"City"},"addressLines":{"type":"array","items":{"type":"string"}}}},"serviceArea":{"type":"object","description":"Areas the business serves. Use updateMask='serviceArea'. Full replacement: send every place you want to keep.","properties":{"businessType":{"type":"string","enum":["CUSTOMER_LOCATION_ONLY","CUSTOMER_AND_BUSINESS_LOCATION"]},"places":{"type":"object","properties":{"placeInfos":{"type":"array","items":{"type":"object","properties":{"placeName":{"type":"string","description":"Localized area name (e.g. 'Sao Paulo, SP, Brasil')"},"placeId":{"type":"string","description":"Google Place ID for the area"}}}}}},"regionCode":{"type":"string","description":"Immutable. CLDR region code of the country the business is based in (e.g. 'BR')"}}},"openInfo":{"type":"object","description":"Open/closed status of the location. Use updateMask='openInfo'.","properties":{"status":{"type":"string","enum":["OPEN","CLOSED_PERMANENTLY","CLOSED_TEMPORARILY"]},"openingDate":{"type":"object","properties":{"year":{"type":"integer"},"month":{"type":"integer"},"day":{"type":"integer"}}}}},"moreHours":{"type":"array","description":"Additional hours for specific services (delivery, drive-through, etc.). Use updateMask='moreHours'.","items":{"type":"object","properties":{"hoursTypeId":{"type":"string","description":"Hours type from Google's catalog (e.g. 'DELIVERY', 'DRIVE_THROUGH')"},"periods":{"type":"array","items":{"type":"object","properties":{"openDay":{"type":"string"},"openTime":{"type":"string"},"closeDay":{"type":"string"},"closeTime":{"type":"string"}}}}}}},"latlng":{"type":"object","description":"Precise coordinates. Use updateMask='latlng'. Google restricts latlng writes to approved clients, so this update may be silently ignored or rejected.","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"}}},"adWordsLocationExtensions":{"type":"object","description":"Alternate phone shown in Google Ads location extensions. Use updateMask='adWordsLocationExtensions'.","properties":{"adPhone":{"type":"string"}}}}},"examples":{"updateHours":{"summary":"Update business hours","value":{"updateMask":"regularHours,specialHours","regularHours":{"periods":[{"openDay":"MONDAY","openTime":"09:00","closeDay":"MONDAY","closeTime":"17:00"},{"openDay":"SATURDAY","openTime":"10:00","closeDay":"SATURDAY","closeTime":"14:00"}]},"specialHours":{"specialHourPeriods":[{"startDate":{"year":2026,"month":12,"day":25},"closed":true},{"startDate":{"year":2026,"month":12,"day":31},"openTime":"09:00","closeTime":"15:00"}]}}},"updateCategories":{"summary":"Update business categories","value":{"updateMask":"categories","categories":{"primaryCategory":{"name":"categories/gcid:laundromat"},"additionalCategories":[{"name":"categories/gcid:dry_cleaner"},{"name":"categories/gcid:laundry_service"}]}}},"updateServices":{"summary":"Update service items","value":{"updateMask":"serviceItems","serviceItems":[{"structuredServiceItem":{"serviceTypeId":"job_type_id:plumbing_drain_repair","description":"Full drain cleaning and repair service"}},{"freeFormServiceItem":{"category":"categories/gcid:laundromat","label":{"displayName":"Wash & Fold Service","languageCode":"en"}},"price":{"currencyCode":"USD","units":"25"}}]}}}}}},"responses":{"200":{"description":"Location updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"locationId":{"type":"string"}}}}}},"400":{"description":"Invalid request or missing updateMask","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized or token expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/accounts/{accountId}/gmb-media":{"get":{"x-resource-group":"accounts","operationId":"listGoogleBusinessMedia","tags":["GMB Media"],"summary":"List media","description":"Lists media items (photos) for a Google Business Profile location.\nReturns photo URLs, descriptions, categories, and metadata.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"locationId","in":"query","schema":{"type":"string"},"description":"Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs."},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Number of items to return (max 100)"},{"name":"pageToken","in":"query","schema":{"type":"string"},"description":"Pagination token from previous response"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Media items fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"locationId":{"type":"string"},"mediaItems":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Resource name"},"mediaFormat":{"type":"string","enum":["PHOTO","VIDEO"]},"sourceUrl":{"type":"string"},"googleUrl":{"type":"string","description":"Google-hosted URL"},"thumbnailUrl":{"type":"string"},"description":{"type":"string"},"createTime":{"type":"string","format":"date-time"},"locationAssociation":{"type":"object","properties":{"category":{"type":"string"}}}}}},"nextPageToken":{"type":"string"},"totalMediaItemsCount":{"type":"integer"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"x-resource-group":"accounts","operationId":"createGoogleBusinessMedia","tags":["GMB Media"],"summary":"Upload photo","description":"Creates a media item (photo) for a location from a publicly accessible URL.\n\nCategories determine where the photo appears: CATEGORY_UNSPECIFIED, COVER, PROFILE, LOGO, EXTERIOR, INTERIOR, PRODUCT, FOOD_AND_DRINK, MENU, COMMON_AREA, ROOMS, TEAMS, AT_WORK, ADDITIONAL.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"locationId","in":"query","schema":{"type":"string"},"description":"Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs."}],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sourceUrl"],"properties":{"sourceUrl":{"type":"string","format":"uri","description":"Publicly accessible image URL"},"mediaFormat":{"type":"string","enum":["PHOTO","VIDEO"],"default":"PHOTO"},"description":{"type":"string","minLength":1,"description":"Photo description"},"category":{"type":"string","enum":["CATEGORY_UNSPECIFIED","COVER","PROFILE","LOGO","EXTERIOR","INTERIOR","PRODUCT","FOOD_AND_DRINK","MENU","COMMON_AREA","ROOMS","TEAMS","AT_WORK","ADDITIONAL"],"description":"Where the photo appears on the listing"}}},"example":{"sourceUrl":"https://example.com/photos/restaurant-interior.jpg","description":"Dining area with outdoor seating","category":"INTERIOR"}}}},"responses":{"200":{"description":"Media created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"name":{"type":"string"},"mediaFormat":{"type":"string"},"googleUrl":{"type":"string"}}}}}},"400":{"description":"Invalid request or unsupported media format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"x-resource-group":"accounts","operationId":"deleteGoogleBusinessMedia","tags":["GMB Media"],"summary":"Delete photo","description":"Deletes a photo or media item from a Google Business Profile location.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"locationId","in":"query","schema":{"type":"string"},"description":"Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs."},{"name":"mediaId","in":"query","required":true,"schema":{"type":"string"},"description":"The media item ID to delete"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Media deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"deleted":{"type":"boolean"},"mediaId":{"type":"string"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/accounts/{accountId}/gmb-attribute-metadata":{"get":{"x-resource-group":"accounts","operationId":"getGmbAttributeMetadata","tags":["GMB Attributes"],"summary":"Get attribute metadata","description":"Returns metadata about which Google Business Profile attributes are available for\na location or business category. Use this endpoint to discover valid attribute names,\nvalue types, and allowed enum values before reading or writing via gmb-attributes.\n\nTwo mutually exclusive query modes:\n\n**Location mode**: pass `locationId` (or rely on the account's stored `selectedLocationId`).\nGoogle returns attributes valid for that specific location.\n\n**Category mode**: pass `categoryName` (must start with `categories/`) and `regionCode`.\nGoogle returns attributes valid for that category across the given region.\n`languageCode` is optional in category mode.\n\nBoth modes support `pageSize` and `pageToken` for pagination.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"locationId","in":"query","schema":{"type":"string"},"description":"Google Business Profile location ID (e.g. \"6257659026299438786\"). If omitted, uses the account's stored selectedLocationId. Mutually exclusive with categoryName.\n"},{"name":"categoryName","in":"query","schema":{"type":"string"},"description":"Category resource name, must start with \"categories/\" (e.g. \"categories/gcid:plumber\"). Required together with regionCode. Mutually exclusive with locationId.\n"},{"name":"regionCode","in":"query","schema":{"type":"string"},"description":"BCP-47 region code (e.g. \"US\", \"ES\"). Required when categoryName is provided.\n"},{"name":"languageCode","in":"query","schema":{"type":"string"},"description":"BCP-47 language code for display names (e.g. \"en\", \"es\"). Optional when categoryName is provided. Omitted from the Google call when not supplied.\n"},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":200},"description":"Maximum number of attribute metadata items to return. Google defaults to 200."},{"name":"pageToken","in":"query","schema":{"type":"string"},"description":"Pagination token from a previous response's nextPageToken field."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Attribute metadata fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"locationId":{"type":"string","description":"Only present in location mode."},"attributeMetadata":{"type":"array","items":{"type":"object","properties":{"parent":{"type":"string","description":"Resource name of the attribute (e.g. \"attributes/has_delivery\")."},"valueType":{"type":"string","description":"Value type (e.g. BOOL, ENUM, URL, REPEATED_ENUM)."},"displayName":{"type":"string","description":"Localized human-readable attribute name."},"groupDisplayName":{"type":"string","description":"Display name of the attribute group."},"repeatable":{"type":"boolean","description":"True if multiple values can be set simultaneously."},"deprecated":{"type":"boolean","description":"True if this attribute should no longer be used."},"valueMetadata":{"type":"array","description":"Possible enum values (for ENUM / REPEATED_ENUM types).","items":{"type":"object","properties":{"value":{"type":"string"},"displayName":{"type":"string"}}}}}}},"nextPageToken":{"type":"string","description":"Present when additional pages of results are available."}}},"example":{"success":true,"accountId":"64f1a2b3c4d5e6f7a8b9c0d1","locationId":"6257659026299438786","attributeMetadata":[{"parent":"attributes/has_delivery","valueType":"BOOL","displayName":"Delivery","groupDisplayName":"Service options"},{"parent":"attributes/pay_credit_card_types_accepted","valueType":"REPEATED_ENUM","displayName":"Credit cards accepted","valueMetadata":[{"value":"visa","displayName":"Visa"},{"value":"mastercard","displayName":"Mastercard"}]}]}}}},"400":{"description":"Invalid request (mixed modes, missing required params, wrong platform, or Google returned 4xx)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"x-summary":"The access token is invalid or revoked: reconnect the Google Business Profile account.","description":"Access token is invalid or revoked. Reconnect the Google Business Profile account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/accounts/{accountId}/gmb-attributes":{"get":{"x-resource-group":"accounts","operationId":"getGoogleBusinessAttributes","tags":["GMB Attributes"],"summary":"Get attributes","description":"Returns Google Business Profile location attributes (amenities, services, accessibility, payment types). Available attributes vary by business category.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"locationId","in":"query","schema":{"type":"string"},"description":"Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Attributes fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"locationId":{"type":"string"},"attributes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Attribute identifier (e.g. has_delivery)"},"valueType":{"type":"string","description":"Value type (BOOL, ENUM, URL, REPEATED_ENUM)"},"values":{"type":"array","items":{}},"repeatedEnumValue":{"type":"object","properties":{"setValues":{"type":"array","items":{"type":"string"}},"unsetValues":{"type":"array","items":{"type":"string"}}}}}}}}},"example":{"success":true,"attributes":[{"name":"has_delivery","valueType":"BOOL","values":[true]},{"name":"has_takeout","valueType":"BOOL","values":[true]},{"name":"has_outdoor_seating","valueType":"BOOL","values":[true]},{"name":"pay_credit_card_types_accepted","valueType":"REPEATED_ENUM","repeatedEnumValue":{"setValues":["visa","mastercard","amex"]}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"x-resource-group":"accounts","operationId":"updateGoogleBusinessAttributes","tags":["GMB Attributes"],"summary":"Update attributes","description":"Updates location attributes (amenities, services, etc.).\n\nThe attributeMask specifies which attributes to update (comma-separated).\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"locationId","in":"query","schema":{"type":"string"},"description":"Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs."}],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["attributes","attributeMask"],"properties":{"attributes":{"type":"array","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1},"valueType":{"type":"string","enum":["ATTRIBUTE_VALUE_TYPE_UNSPECIFIED","BOOL","ENUM","URL","REPEATED_ENUM"]},"values":{"type":"array","items":{}},"repeatedEnumValue":{"type":"object","properties":{"setValues":{"type":"array","items":{"type":"string"}},"unsetValues":{"type":"array","items":{"type":"string"}}}},"uriValues":{"type":"array","items":{"type":"object","required":["uri"],"properties":{"uri":{"type":"string","format":"uri"}}}}}}},"attributeMask":{"type":"string","minLength":1,"description":"Comma-separated attribute names to update (e.g. 'has_delivery,has_takeout')"}}},"example":{"attributes":[{"name":"has_delivery","values":[true]},{"name":"has_takeout","values":[true]},{"name":"has_outdoor_seating","values":[false]}],"attributeMask":"has_delivery,has_takeout,has_outdoor_seating"}}}},"responses":{"200":{"description":"Attributes updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"locationId":{"type":"string"},"attributes":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/accounts/{accountId}/gmb-place-actions":{"get":{"x-resource-group":"accounts","operationId":"listGoogleBusinessPlaceActions","tags":["GMB Place Actions"],"summary":"List action links","description":"Lists place action links for a Google Business Profile location.\n\nPlace actions are the booking, ordering, and reservation buttons that appear on your listing.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"locationId","in":"query","schema":{"type":"string"},"description":"Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs."},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"pageToken","in":"query","schema":{"type":"string"}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Place actions fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"locationId":{"type":"string"},"placeActionLinks":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Resource name"},"uri":{"type":"string","description":"Action URL"},"placeActionType":{"type":"string"},"createTime":{"type":"string","format":"date-time"},"updateTime":{"type":"string","format":"date-time"}}}},"nextPageToken":{"type":"string"}}},"example":{"success":true,"placeActionLinks":[{"name":"locations/123/placeActionLinks/456","uri":"https://order.ubereats.com/joespizza","placeActionType":"FOOD_ORDERING"},{"name":"locations/123/placeActionLinks/789","uri":"https://www.opentable.com/joespizza","placeActionType":"DINING_RESERVATION"}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"x-resource-group":"accounts","operationId":"createGoogleBusinessPlaceAction","tags":["GMB Place Actions"],"summary":"Create action link","description":"Creates a place action link for a location.\n\nAvailable action types: APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"locationId","in":"query","schema":{"type":"string"},"description":"Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs."}],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["uri","placeActionType"],"properties":{"uri":{"type":"string","format":"uri","description":"The action URL"},"placeActionType":{"type":"string","enum":["APPOINTMENT","ONLINE_APPOINTMENT","DINING_RESERVATION","FOOD_ORDERING","FOOD_DELIVERY","FOOD_TAKEOUT","SHOP_ONLINE"],"description":"Type of action"}}},"example":{"uri":"https://order.ubereats.com/joespizza","placeActionType":"FOOD_ORDERING"}}}},"responses":{"200":{"description":"Place action created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"name":{"type":"string","description":"Resource name of the created link"},"uri":{"type":"string"},"placeActionType":{"type":"string"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"x-resource-group":"accounts","operationId":"deleteGoogleBusinessPlaceAction","tags":["GMB Place Actions"],"summary":"Delete action link","description":"Deletes a place action link (e.g. booking or ordering URL) from a Google Business Profile location.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"locationId","in":"query","schema":{"type":"string"},"description":"Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs."},{"name":"name","in":"query","required":true,"schema":{"type":"string"},"description":"The resource name of the place action link (e.g. locations/123/placeActionLinks/456)"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Place action deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"deleted":{"type":"boolean"},"name":{"type":"string"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"x-resource-group":"accounts","operationId":"updateGoogleBusinessPlaceAction","tags":["GMB Place Actions"],"summary":"Update action link","description":"Updates a place action link (change URL or action type).\nOnly the fields included in the request body will be updated.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"locationId","in":"query","schema":{"type":"string"},"description":"Override which location to target. If omitted, uses the account's selected location."}],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Resource name of the place action link (e.g. locations/123/placeActionLinks/456)"},"uri":{"type":"string","format":"uri","description":"New action URL. At least one of uri or placeActionType is required (enforced server-side; not modeled as anyOf because required-only anyOf branches break SDK generators)."},"placeActionType":{"type":"string","enum":["APPOINTMENT","ONLINE_APPOINTMENT","DINING_RESERVATION","FOOD_ORDERING","FOOD_DELIVERY","FOOD_TAKEOUT","SHOP_ONLINE"],"description":"New action type"}}},"example":{"name":"locations/123/placeActionLinks/456","uri":"https://order.doordash.com/joespizza"}}}},"responses":{"200":{"description":"Place action updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"name":{"type":"string"},"uri":{"type":"string"},"placeActionType":{"type":"string"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/accounts/{accountId}/gmb-services":{"get":{"x-resource-group":"accounts","operationId":"getGoogleBusinessServices","tags":["GMB Services"],"summary":"Get services","description":"Gets the services offered by a Google Business Profile location.\nReturns an array of service items (structured or free-form with optional price).\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"locationId","in":"query","schema":{"type":"string"},"description":"Override which location to query. If omitted, uses the account's selected location."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Services fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"locationId":{"type":"string"},"services":{"type":"array","items":{"type":"object","properties":{"structuredServiceItem":{"type":"object","properties":{"serviceTypeId":{"type":"string"},"description":{"type":"string"}}},"freeFormServiceItem":{"type":"object","properties":{"category":{"type":"string"},"label":{"type":"object","properties":{"displayName":{"type":"string"},"description":{"type":"string"}}}}},"price":{"type":"object","properties":{"currencyCode":{"type":"string","example":"USD"},"units":{"type":"string","example":"50"},"nanos":{"type":"integer"}}}}}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"x-resource-group":"accounts","operationId":"updateGoogleBusinessServices","tags":["GMB Services"],"summary":"Replace services","description":"Replaces the entire service list for a location.\nGoogle's API requires full replacement; individual item updates are not supported.\nEach service can be structured (using a predefined serviceTypeId) or free-form (custom label).\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"locationId","in":"query","schema":{"type":"string"},"description":"Override which location to target. If omitted, uses the account's selected location."}],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["serviceItems"],"properties":{"serviceItems":{"type":"array","items":{"type":"object","properties":{"structuredServiceItem":{"type":"object","required":["serviceTypeId"],"description":"Exactly one of structuredServiceItem or freeFormServiceItem is required per item (enforced server-side; not modeled as oneOf because required-only oneOf branches break SDK generators).","properties":{"serviceTypeId":{"type":"string","minLength":1},"description":{"type":"string"}}},"freeFormServiceItem":{"type":"object","required":["category","label"],"properties":{"category":{"type":"string","minLength":1},"label":{"type":"object","required":["displayName"],"properties":{"displayName":{"type":"string","minLength":1},"description":{"type":"string"},"languageCode":{"type":"string"}}}}},"price":{"type":"object","properties":{"currencyCode":{"type":"string","minLength":1},"units":{"type":"string","minLength":1},"nanos":{"type":"integer"}}}}}}}},"example":{"serviceItems":[{"freeFormServiceItem":{"category":"categories/gcid:plumber","label":{"displayName":"Pipe Repair","description":"Emergency and scheduled pipe repair"}},"price":{"currencyCode":"USD","units":"150"}}]}}}},"responses":{"200":{"description":"Services updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"services":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/accounts/{accountId}/gmb-reviews/batch":{"post":{"x-resource-group":"engagement","operationId":"batchGetGoogleBusinessReviews","tags":["GMB Reviews"],"summary":"Batch get reviews","description":"Fetches reviews across multiple locations in a single request. More efficient than calling GET /gmb-reviews per location for multi-location businesses.\n\n### Response\n\nReturns a flat locationReviews array (not grouped by location). Each item carries:\n\n- `name`: the location resource name it belongs to.\n- `review`: the review object, whose identity is `review.reviewId`.\n\n### Ordering\n\nReviews are requested from Google ordered by `orderBy` (default `updateTime desc`, newest first). Callers polling for recent reviews can stop paginating once they cross their date window.\n\n### Aggregate metrics\n\nThis endpoint does not return aggregate metrics (averageRating / totalReviewCount). For those, use the single-location GET /gmb-reviews endpoint.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["locationNames"],"properties":{"locationNames":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","pattern":"^accounts/[^/]+/locations/[^/]+$"},"description":"Array of full location resource names (e.g. ['accounts/123/locations/456']). Max 50 per request (Google's batchGetReviews cap); chunk larger sets into multiple requests."},"pageSize":{"type":"integer","minimum":1,"maximum":50,"default":50,"description":"Number of reviews per page (max 50)"},"pageToken":{"type":"string","minLength":1,"description":"Pagination token from previous response"},"orderBy":{"type":"string","enum":["updateTime desc","rating","rating desc"],"default":"updateTime desc","description":"Sort order requested from Google. Defaults to 'updateTime desc' (newest first), which allows early-stopping pagination once results cross your date window."}}},"example":{"locationNames":["accounts/123/locations/456","accounts/123/locations/789"],"pageSize":50}}}},"responses":{"200":{"description":"Batch reviews fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"locationReviews":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"LOCATION resource name the review belongs to (accounts/{accountId}/locations/{locationId}) - NOT the review resource name. Use it to attribute the review to a location; the review identity is review.reviewId (full review resource name at review.name)."},"review":{"type":"object","description":"The review object: reviewId (the review's identity), name (full review resource name, accounts/*/locations/*/reviews/*), starRating, comment, reviewer, createTime, updateTime, reviewReply, and reviewMediaItems (review photos/videos; photo items carry thumbnailUrl, video items carry videoUrl)"}}}},"nextPageToken":{"type":"string"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/accounts/{accountId}/gmb-reviews/{reviewId}":{"get":{"x-resource-group":"engagement","operationId":"getGoogleBusinessReview","tags":["GMB Reviews"],"summary":"Get a review","description":"Returns one Google Business Profile review, in the same shape as the entries of GET /v1/accounts/{accountId}/gmb-reviews.\n\nThe review is read from the account's selected location unless locationId overrides it. Google returns 404 for a review id that belongs to another location.\n\nRead the review before replying if a human may have answered it already: replies are overwritten in place and Google keeps no history.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"The Zernio account ID (from /v1/accounts)"},{"name":"reviewId","in":"path","required":true,"schema":{"type":"string"},"description":"The review ID portion (e.g. \"AIe9_BGx1234567890\"), not the full resource name"},{"name":"locationId","in":"query","schema":{"type":"string"},"description":"Override which location to read the review from. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Review fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accountId":{"type":"string"},"locationId":{"type":"string"},"review":{"$ref":"#/components/schemas/GoogleBusinessReview"}}},"example":{"success":true,"accountId":"64e1f0a9e2b5af0012ab34cd","locationId":"9281089117903930794","review":{"id":"AIe9_BGx1234567890","name":"accounts/123456789/locations/9281089117903930794/reviews/AIe9_BGx1234567890","reviewer":{"displayName":"John Smith","profilePhotoUrl":"https://lh3.googleusercontent.com/a/...","isAnonymous":false},"rating":5,"starRating":"FIVE","comment":"Great service and friendly staff! Highly recommend.","createTime":"2024-01-15T10:30:00Z","updateTime":"2024-01-15T10:30:00Z","reviewReply":{"comment":"Thank you for your kind words! We appreciate your support.","updateTime":"2024-01-16T08:00:00Z"},"photoCount":0,"photos":[]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Unauthorized or token invalid (account must be reconnected)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Access token invalid. Please reconnect your Google Business Profile account.","code":"token_invalid"}}}},"404":{"description":"Account not found, or no such review on this location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to fetch the review","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/accounts/{accountId}/gmb-reviews/{reviewId}/reply":{"post":{"x-resource-group":"engagement","operationId":"replyToGoogleBusinessReview","tags":["GMB Reviews"],"summary":"Reply to a review","description":"Posts (or updates) the business owner reply to a Google Business Profile review.\n\nThe reply is associated with the account's currently selected location (set via /v1/accounts/{accountId}/gmb-locations).\n\n### Overwrites\n\nCalling this endpoint a second time on the same review overwrites the previous reply (PUT semantics on Google's side).\n\nGoogle keeps no history, so an automated retry silently replaces a reply someone edited by hand in the Google Business Profile UI. Read the review before retrying if a human may have answered it.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"The Zernio account ID (from /v1/accounts)"},{"name":"reviewId","in":"path","required":true,"schema":{"type":"string"},"description":"The review ID portion (e.g. \"AIe9_BGx1234567890\"), not the full resource name"}],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["comment"],"properties":{"comment":{"type":"string","minLength":1,"description":"The reply text to post on the review. Must be non-empty."}}},"example":{"comment":"Thank you for your kind words, we really appreciate it!"}}}},"responses":{"200":{"description":"Reply posted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"reviewId":{"type":"string"},"platform":{"type":"string","example":"googlebusiness"}}},"example":{"success":true,"reviewId":"AIe9_BGx1234567890","platform":"googlebusiness"}}}},"400":{"description":"Invalid request, missing comment, non-Google Business Profile account, or account missing location metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"comment is required and must be a non-empty string"}}}},"401":{"description":"Unauthorized or token invalid (account must be reconnected)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Access token invalid. Please reconnect your Google Business Profile account.","code":"token_invalid"}}}},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"Failed to post reply","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"x-resource-group":"engagement","operationId":"deleteGoogleBusinessReviewReply","tags":["GMB Reviews"],"summary":"Delete a review reply","description":"Removes the business owner reply from a Google Business Profile review. The review itself remains.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"The Zernio account ID (from /v1/accounts)"},{"name":"reviewId","in":"path","required":true,"schema":{"type":"string"},"description":"The review ID portion (e.g. \"AIe9_BGx1234567890\"), not the full resource name"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Reply deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"platform":{"type":"string","example":"googlebusiness"}}},"example":{"success":true,"message":"Reply deleted successfully","platform":"googlebusiness"}}}},"400":{"description":"Invalid request, non-Google Business Profile account, or account missing location metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized or token invalid (account must be reconnected)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Access token invalid. Please reconnect your Google Business Profile account.","code":"token_invalid"}}}},"404":{"$ref":"#/components/responses/NotFound"},"500":{"description":"Failed to delete reply","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/connect/handoffs/{handoffId}":{"get":{"x-resource-group":"accounts","operationId":"getConnectHandoff","tags":["Connect"],"summary":"Get a phone handoff","description":"Shows where a connect started with `handoff=true` on `GET /v1/connect/{platform}` stands.\n\n### States\n\n- `waiting`: until the QR code is scanned\n- `opened`: the phone opened it\n- `connected`: with the new accounts\n- `failed`: with the error the flow ended on (the same `error` codes as the redirect flow)\n- `expired`: nobody opened the QR code within its 30 minutes\n\n### Polling\n\nPoll it every 2 to 5 seconds while your QR code is shown, and stop once it is `connected`, `failed` or `expired`.\n\nIt is readable for 60 minutes after it was created, then 404. A handoff created by another workspace is also 404.\n","parameters":[{"name":"handoffId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"`handoff.id` from the connect response."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The handoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectHandoff"},"example":{"id":"79c6dbf2-97ba-4f34-b615-5bf9435526db","status":"connected","platform":"instagram","accounts":[{"id":"6ab0c2f1e4d5a6b7c8d9e0f1","profileId":"69b0a1b2c3d4e5f6a7b8c9d0","username":"acme"}],"error":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"The handoff expired, does not exist, or belongs to another workspace (code RESOURCE_NOT_FOUND)."}}}},"/v1/connect/welcome-screen":{"get":{"x-resource-group":"accounts","operationId":"getConnectWelcomeScreen","tags":["Connect"],"summary":"Get the saved welcome screen","description":"The workspace's saved welcome screen settings, shared by the whole team. With `showByDefault` on, every `GET /v1/connect/{platform}` made with your API key shows the welcome screen before the platform's authorization screen, without `welcome=true` or any branding parameter. Connects started from the Zernio dashboard always show it, with this branding when saved.","security":[{"bearerAuth":[]}],"responses":{"200":{"x-summary":"The saved connect welcome screen settings are returned, with defaults when the workspace never saved any.","description":"The saved settings. A workspace that never saved any gets `showByDefault` false and null fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectWelcomeScreen"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"put":{"x-resource-group":"accounts","operationId":"updateConnectWelcomeScreen","tags":["Connect"],"summary":"Save the welcome screen","description":"Replaces the workspace's welcome screen settings: a field left out is cleared. Only the account owner or a full-access team member can save, and not with a profile-scoped API key. Parameters sent on a connect call still win over these values for that call.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["showByDefault"],"properties":{"showByDefault":{"type":"boolean","description":"Show the welcome screen on connect calls that do not pass `welcome`."},"brandName":{"type":"string","minLength":1,"maxLength":60},"logoUrl":{"type":"string","format":"uri","maxLength":2048,"description":"https URL of a square logo."},"theme":{"type":"object","description":"Same keys as the `welcomeTheme` parameter of `GET /v1/connect/{platform}`, as a JSON object."}}},"example":{"showByDefault":true,"brandName":"Acme","logoUrl":"https://acme.com/logo.png","theme":{"primaryColor":"#1D4ED8","cornerRadius":12}}}}},"responses":{"200":{"description":"The saved settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectWelcomeScreen"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The caller cannot change workspace settings (code INSUFFICIENT_PERMISSIONS)."}}}},"/v1/connect/oauth-apps":{"get":{"x-resource-group":"accounts","operationId":"listOAuthApps","tags":["Connect"],"summary":"List your OAuth apps","description":"Lists your own OAuth apps on social platforms. Add as many as you need, any number per platform.\n\nA connect runs on one when it passes its id as `oauthAppId`. The consent screen then shows your app's name and logo, and the platform's rate limits and quotas are your app's.\n\nAlso lists, in `platforms`, which platforms accept your own app and what to set up on each.\n\nPages are ordered by id: pass `pagination.nextCursor` back as `cursor` until it is null.\n\nLike every OAuth-app call, it needs the account owner or a full-access team member, on a session or a full-scope API key.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"`pagination.nextCursor` from the previous page."}],"responses":{"200":{"description":"Your apps, and the platforms that accept one.","content":{"application/json":{"schema":{"type":"object","required":["apps","pagination","platforms"],"properties":{"apps":{"type":"array","items":{"$ref":"#/components/schemas/OAuthApp"}},"pagination":{"type":"object","required":["nextCursor"],"properties":{"nextCursor":{"type":["string","null"],"description":"Null on the last page."}}},"platforms":{"type":"array","items":{"$ref":"#/components/schemas/OAuthAppSetup"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"x-resource-group":"accounts","operationId":"createOAuthApp","tags":["Connect"],"summary":"Add an OAuth app","description":"Saves your app's client ID and secret for a platform.\n\nThe keys are checked with the platform first:\n\n- Keys it rejects return 400 OAUTH_APP_KEYS_REJECTED and are not saved.\n- Keys it could not check are saved with status `unchecked`.\n\nAllow the returned `redirectUri` in your app's settings on the platform before connecting.\n\nOnly the account owner or a full-access team member can add apps, and not with a profile-scoped API key.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["platform","label","clientId","clientSecret"],"properties":{"platform":{"type":"string","description":"One of the platforms listed in `platforms` of GET /v1/connect/oauth-apps."},"label":{"type":"string","minLength":1,"maxLength":80},"clientId":{"type":"string","minLength":1,"maxLength":500},"clientSecret":{"type":"string","minLength":1,"maxLength":1000},"metaAppId":{"type":"string","pattern":"^\\d{1,32}$","description":"Instagram only: the numeric ID of the Meta app your Instagram app lives in. Zernio uses it with `metaAppSecret` to register the webhook. Send both or neither."},"metaAppSecret":{"type":"string","minLength":1,"maxLength":1000,"description":"Instagram only: the secret of that Meta app. Never returned."},"slackSigningSecret":{"type":"string","minLength":1,"maxLength":1000,"description":"Slack only: the signing secret from the app's Basic Information page. Needed to receive events from your Slack app; any other platform is a 400."},"scopeAreas":{"type":"array","items":{"type":"string","enum":["posting","analytics","comments","messaging"]},"description":"Areas this app requests. Defaults to every area the platform supports; an area the platform cannot request separately is a 400."}}},"example":{"platform":"youtube","label":"Acme","clientId":"1234567890-abc.apps.googleusercontent.com","clientSecret":"GOCSPX-xxxxxxxx"}}}},"responses":{"201":{"description":"The app was saved.","content":{"application/json":{"schema":{"type":"object","required":["app"],"properties":{"app":{"$ref":"#/components/schemas/OAuthApp"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The caller cannot change workspace settings (INSUFFICIENT_PERMISSIONS)."},"409":{"x-summary":"The workspace already has an OAuth app with this client ID on this platform: update its secret instead, using `details.appId`.","description":"The workspace already has an app with this client ID on this platform (OAUTH_APP_ALREADY_EXISTS); `details.appId` names it. Rotate its secret with PATCH instead."}}}},"/v1/connect/oauth-apps/{appId}":{"parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"x-resource-group":"accounts","operationId":"getOAuthApp","tags":["Connect"],"summary":"Get an OAuth app","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The app.","content":{"application/json":{"schema":{"type":"object","required":["app"],"properties":{"app":{"$ref":"#/components/schemas/OAuthApp"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"x-resource-group":"accounts","operationId":"updateOAuthApp","tags":["Connect"],"summary":"Update an OAuth app","description":"Renames the app or rotates its secret.\n\nA new secret is checked with the platform before it is saved, and takes effect for every account on the app at once; their tokens keep working.\n\nThe client ID cannot change: a different client ID is a different app, so add it and reconnect the accounts through it.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"label":{"type":"string","minLength":1,"maxLength":80},"clientSecret":{"type":"string","minLength":1,"maxLength":1000},"metaAppId":{"type":"string","pattern":"^\\d{1,32}$","description":"Instagram only: the numeric ID of the Meta app your Instagram app lives in. Zernio uses it with `metaAppSecret` to register the webhook. Send both or neither."},"metaAppSecret":{"type":"string","minLength":1,"maxLength":1000,"description":"Instagram only: the secret of that Meta app. Never returned."},"slackSigningSecret":{"type":"string","minLength":1,"maxLength":1000,"description":"Slack only: saves or replaces the signing secret from the app's Basic Information page; any other platform is a 400."},"scopeAreas":{"type":"array","items":{"type":"string","enum":["posting","analytics","comments","messaging"]},"description":"Replaces the areas new connects request. Accounts already connected keep what they were granted until they reconnect."}}}}}},"responses":{"200":{"description":"The updated app.","content":{"application/json":{"schema":{"type":"object","required":["app"],"properties":{"app":{"$ref":"#/components/schemas/OAuthApp"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The caller cannot change workspace settings (INSUFFICIENT_PERMISSIONS)."},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"x-resource-group":"accounts","operationId":"deleteOAuthApp","tags":["Connect"],"summary":"Remove an OAuth app","description":"Removes the app. Accounts connected through it can no longer refresh their tokens, so when any are connected the call returns 409 OAUTH_APP_IN_USE with `details.accountCount` unless `confirm=true` is passed. With confirm, those accounts are marked as needing reconnection and each fires `account.disconnected`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"confirm","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"The app was removed.","content":{"application/json":{"schema":{"type":"object","required":["disconnectedAccounts"],"properties":{"disconnectedAccounts":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The caller cannot change workspace settings (INSUFFICIENT_PERMISSIONS)."},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Accounts are still connected through the app (OAUTH_APP_IN_USE); resend with confirm=true."}}}},"/v1/connect/oauth-apps/{appId}/test":{"post":{"x-resource-group":"accounts","operationId":"testOAuthApp","tags":["Connect"],"summary":"Check an OAuth app's keys","description":"Checks the saved keys with the platform again and records the outcome in `status` and `lastError`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The app with the new check result.","content":{"application/json":{"schema":{"type":"object","required":["app"],"properties":{"app":{"$ref":"#/components/schemas/OAuthApp"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/connect/pending-data":{"get":{"x-resource-group":"public","operationId":"getPendingOAuthData","tags":["Connect"],"summary":"Get pending OAuth data","description":"Fetch pending OAuth data for headless mode using the pendingDataToken from the redirect URL. No authentication required.\n\n### Scope\n\nThis endpoint is used where the selection list is too large to fit in URL params:\n\n- LinkedIn organizations\n- Google Business Profile locations\n- Slack channels\n- Snapchat profiles\n- Pinterest boards\n\nThe redirect carries a `pendingDataToken` instead of the full payload. The response includes the corresponding selection array (e.g. `boards` for Pinterest).\n\nWhatsApp, Facebook and other platforms pass selection state directly via URL query params on the redirect (`profileId`, `tempToken`, `step`), and no pending record is created. So this endpoint will return 404 for those flows. Use the platform-specific selection endpoint instead (e.g. `/v1/connect/whatsapp/select-phone-number`).\n\n### Token lifetime\n\nReading the token does not consume it, so this fetch is repeatable until the token expires 1 hour after issuance.\n\nCompleting the platform selection deletes the pending record, so the token stops working from then on.\n","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"},"description":"The pending data token from the OAuth redirect URL (pendingDataToken parameter)"}],"responses":{"200":{"description":"OAuth data fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","description":"The platform (e.g., \"linkedin\")"},"profileId":{"type":"string","description":"The Zernio profile ID"},"tempToken":{"type":"string","description":"Temporary access token for the platform"},"refreshToken":{"type":"string","description":"Refresh token (if available)"},"expiresIn":{"type":"number","description":"Token expiry in seconds"},"userProfile":{"type":"object","description":"User profile data (id, username, displayName, profilePicture)"},"selectionType":{"type":"string","enum":["organizations","pages","boards","locations","profiles"],"description":"Type of selection data"},"organizations":{"type":"array","description":"LinkedIn organizations (when selectionType is \"organizations\")","items":{"type":"object","properties":{"id":{"type":"string"},"urn":{"type":"string"},"name":{"type":"string"},"vanityName":{"type":"string"}}}}}},"example":{"platform":"linkedin","profileId":"abc123","tempToken":"AQV...","refreshToken":"AQW...","expiresIn":5183999,"userProfile":{"id":"ABC123","username":"John Doe","displayName":"John Doe","profilePicture":"https://..."},"selectionType":"organizations","organizations":[{"id":"12345","urn":"urn:li:organization:12345","name":"Acme Corp","vanityName":"acme-corp"},{"id":"67890","urn":"urn:li:organization:67890","name":"Example Inc","vanityName":"example-inc"}]}}}},"400":{"description":"Missing token parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Token not found or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/connect/linkedin/organizations":{"get":{"x-resource-group":"public","operationId":"listLinkedInOrganizations","tags":["Connect"],"summary":"List LinkedIn orgs","description":"Fetch full LinkedIn organization details (logos, vanity names, websites) for custom UI. No authentication required, only the tempToken from OAuth.","parameters":[{"name":"tempToken","in":"query","required":true,"schema":{"type":"string"},"description":"The temporary LinkedIn access token from the OAuth redirect"},{"name":"orgIds","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated list of organization IDs to fetch details for (max 100)","example":"12345678,87654321,11111111"}],"responses":{"200":{"description":"Organization details fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"organizations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Organization ID"},"logoUrl":{"type":"string","format":"uri","description":"Logo URL (may be absent if no logo)"},"vanityName":{"type":"string","description":"Organization's vanity name/slug"},"website":{"type":"string","format":"uri","description":"Organization's website URL"},"industry":{"type":"string","description":"Organization's primary industry"},"description":{"type":"string","description":"Organization's description"}}}}}},"example":{"organizations":[{"id":"12345678","logoUrl":"https://media.licdn.com/dms/image/v2/...","vanityName":"acme-corp","website":"https://acme.com","industry":"Technology","description":"Leading provider of innovative solutions"},{"id":"87654321","logoUrl":"https://media.licdn.com/dms/image/v2/...","vanityName":"example-inc","website":"https://example.com"},{"id":"11111111"}]}}}},"400":{"description":"Missing required parameters or too many organization IDs","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"Missing tempToken parameter"}}}},"500":{"description":"Failed to fetch organization details"}}}},"/v1/connect/linkedin/select-organization":{"post":{"x-resource-group":"accounts","operationId":"selectLinkedInOrganization","tags":["Connect"],"summary":"Select LinkedIn org","description":"Complete the LinkedIn connection flow. Set accountType to \"personal\" or \"organization\" to connect as a company page. Use X-Connect-Token if connecting via API key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","tempToken","userProfile"],"properties":{"profileId":{"type":"string"},"tempToken":{"type":"string"},"userProfile":{"type":"object"},"accountType":{"type":"string","enum":["personal","organization"],"description":"Send this (with selectedOrganization for an organization) or selections, not both."},"selections":{"type":"array","minItems":1,"maxItems":25,"description":"Several accounts to connect from one sign-in (yourself and/or organizations), each as its own account. With two or more entries the response lists `accounts` and `failed` instead of `account`, and the request is refused with 400 on a reconnect or an ads connect. A single entry behaves exactly like accountType.","items":{"type":"object","required":["accountType"],"properties":{"accountType":{"type":"string","enum":["personal","organization"]},"selectedOrganization":{"type":"object","description":"Same shape as selectedOrganization."}}}},"selectedOrganization":{"type":"object","required":["id","urn","name"],"properties":{"id":{"type":"string","minLength":1},"urn":{"type":"string","pattern":"^urn:li:organization:"},"name":{"type":"string","minLength":1},"logoUrl":{"type":"string","format":"uri"},"vanityName":{"type":"string"}}},"redirect_url":{"type":"string","format":"uri"}}},"examples":{"personalAccount":{"summary":"Connect as personal LinkedIn profile","description":"For personal accounts, set accountType to \"personal\" and omit selectedOrganization","value":{"profileId":"64f0a1b2c3d4e5f6a7b8c9d0","tempToken":"AQX...","userProfile":{"id":"abc123","username":"johndoe","displayName":"John Doe","profilePicture":"https://media.licdn.com/dms/image/v2/..."},"accountType":"personal"}},"organizationAccount":{"summary":"Connect as org/company page","description":"For organization pages, include the selectedOrganization object","value":{"profileId":"64f0a1b2c3d4e5f6a7b8c9d0","tempToken":"AQX...","userProfile":{"id":"abc123","username":"johndoe","displayName":"John Doe","profilePicture":"https://media.licdn.com/dms/image/v2/..."},"accountType":"organization","selectedOrganization":{"id":"12345678","urn":"urn:li:organization:12345678","name":"Acme Corporation"},"redirect_url":"https://yourapp.com/callback"}}}}}},"responses":{"200":{"description":"LinkedIn account connected","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"redirect_url":{"type":"string","description":"The redirect URL with connection params appended (only if redirect_url was provided in request)"},"account":{"type":"object","properties":{"accountId":{"type":"string","description":"ID of the created SocialAccount"},"platform":{"type":"string","enum":["linkedin"]},"username":{"type":"string"},"displayName":{"type":"string"},"profilePicture":{"type":"string"},"isActive":{"type":"boolean"},"accountType":{"type":"string","enum":["personal","organization"]}}},"accounts":{"type":"array","description":"selections only. The connected accounts, same shape as `account`. The redirect_url then carries `accountIds` (comma-separated) and `accountId` of the first.","items":{"type":"object"}},"failed":{"type":"array","description":"selections only. The accounts that could not be connected while the others were. `id` is the organization URN or the member id, or `selections[i]` for an entry naming neither.","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"bulkRefresh":{"type":"object","properties":{"updatedCount":{"type":"integer"},"errors":{"type":"integer"}}}}},"examples":{"personalAccountResponse":{"summary":"Personal account connected","value":{"message":"LinkedIn account connected successfully","account":{"accountId":"64e1f0a9e2b5af0012ab34cd","platform":"linkedin","username":"johndoe","displayName":"John Doe","profilePicture":"https://media.licdn.com/...","isActive":true,"accountType":"personal"}}},"organizationWithRedirect":{"summary":"Org account with redirect URL","value":{"message":"LinkedIn account connected successfully","redirect_url":"https://yourapp.com/callback?connected=linkedin&profileId=507f1f77bcf86cd799439011&accountId=64e1f0a9e2b5af0012ab34cd&username=Acme+Corporation","account":{"accountId":"64e1f0a9e2b5af0012ab34cd","platform":"linkedin","username":"acme-corp","displayName":"Acme Corporation","profilePicture":"https://media.licdn.com/...","isActive":true,"accountType":"organization"},"bulkRefresh":{"updatedCount":5,"errors":0}}}}}}},"400":{"description":"Missing required fields"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The connect token was issued for a different profile or platform (INSUFFICIENT_PERMISSIONS)."},"409":{"x-summary":"The sign-in behind the temporary token was already used or has expired: start a new sign-in.","description":"The sign-in behind tempToken was already used by an earlier selection or has expired (code oauth_sign_in_consumed); start a new sign-in or send refreshToken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"x-summary":"None of the selected organizations could be connected: read `details.failed` for each reason and fix them.","description":"selections only. None of the accounts could be connected; `details.failed` lists each one with its reason.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to connect LinkedIn account"}}}},"/v1/connect/pinterest/select-board":{"get":{"x-resource-group":"accounts","operationId":"listPinterestBoardsForSelection","tags":["Connect"],"summary":"List Pinterest boards","description":"For headless flows. Returns Pinterest boards the user can post to. Use X-Connect-Token from the redirect URL.","parameters":[{"name":"X-Connect-Token","in":"header","required":true,"schema":{"type":"string"},"description":"Short-lived connect token from the OAuth redirect"},{"name":"profileId","in":"query","required":true,"schema":{"type":"string"},"description":"Your Zernio profile ID"},{"name":"tempToken","in":"query","required":true,"schema":{"type":"string"},"description":"Temporary Pinterest access token from the OAuth callback redirect"}],"responses":{"200":{"description":"List of Pinterest Boards available for connection","content":{"application/json":{"schema":{"type":"object","properties":{"boards":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Pinterest Board ID"},"name":{"type":"string","description":"Board name"},"description":{"type":"string","description":"Board description"},"privacy":{"type":"string","description":"Board privacy setting"}}}}}},"example":{"boards":[{"id":"123456789012345678","name":"Marketing Ideas","description":"Collection of marketing inspiration","privacy":"PUBLIC"},{"id":"234567890123456789","name":"Product Photos","description":"Product photography","privacy":"PUBLIC"}]}}}},"400":{"description":"Missing required parameters"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"No access to profile"},"500":{"description":"Failed to fetch boards"}}},"post":{"x-resource-group":"accounts","operationId":"selectPinterestBoard","tags":["Connect"],"summary":"Select Pinterest board","description":"Complete the Pinterest connection flow. After OAuth, use this endpoint to save the selected board and complete the account connection. Use the X-Connect-Token header if you initiated the connection via API key.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","boardId","tempToken"],"properties":{"profileId":{"type":"string","description":"Your Zernio profile ID"},"boardId":{"type":"string","description":"The Pinterest Board ID selected by the user"},"boardName":{"type":"string","description":"The board name (for display purposes)"},"tempToken":{"type":"string","description":"Temporary Pinterest access token from OAuth"},"userProfile":{"type":"object","description":"User profile data from OAuth redirect"},"refreshToken":{"type":"string","description":"Pinterest refresh token (if available)"},"expiresIn":{"type":"integer","description":"Token expiration time in seconds"},"redirect_url":{"type":"string","format":"uri","description":"Custom redirect URL after connection completes"},"oauthAppId":{"type":"string","description":"The `oauthAppId` from the selection redirect, when the connect ran on one of your own OAuth apps. Pass it back so a retried selection stays on that app; a different app than the connect used returns 400."}}},"example":{"profileId":"64f0a1b2c3d4e5f6a7b8c9d0","boardId":"123456789012345678","boardName":"Marketing Ideas","tempToken":"pina_...","userProfile":{"id":"user123","username":"mybrand","displayName":"My Brand","profilePicture":"https://i.pinimg.com/..."},"redirect_url":"https://yourapp.com/callback"}}}},"responses":{"200":{"description":"Pinterest Board connected successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"redirect_url":{"type":"string","description":"Redirect URL with connection params (if provided)"},"account":{"type":"object","properties":{"accountId":{"type":"string","description":"ID of the created SocialAccount"},"platform":{"type":"string","enum":["pinterest"]},"username":{"type":"string"},"displayName":{"type":"string"},"profilePicture":{"type":"string"},"isActive":{"type":"boolean"},"defaultBoardName":{"type":"string"}}}}},"example":{"message":"Pinterest connected successfully with default board","redirect_url":"https://yourdomain.com/integrations/callback?connected=pinterest&profileId=507f1f77bcf86cd799439011&accountId=64e1f0a9e2b5af0012ab34cd&board=Marketing+Ideas","account":{"accountId":"64e1f0a9e2b5af0012ab34cd","platform":"pinterest","username":"mybrand","displayName":"My Brand","profilePicture":"https://i.pinimg.com/...","isActive":true,"defaultBoardName":"Marketing Ideas"}}}}},"400":{"description":"Missing required fields","content":{"application/json":{"example":{"error":"Missing required fields"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"No access to profile or profile limit exceeded","content":{"application/json":{"examples":{"forbidden":{"value":{"error":"Forbidden"}},"limitExceeded":{"value":{"error":"Cannot connect to this profile. It exceeds your Pro plan limit of 5 profiles.","code":"PROFILE_LIMIT_EXCEEDED"}}}}}},"500":{"description":"Failed to save Pinterest connection"}}}},"/v1/connect/snapchat/select-profile":{"get":{"x-resource-group":"accounts","operationId":"listSnapchatProfiles","tags":["Connect"],"summary":"List Snapchat profiles","description":"For headless flows. Returns Snapchat Public Profiles the user can post to. Use X-Connect-Token from the redirect URL.","parameters":[{"name":"X-Connect-Token","in":"header","required":true,"schema":{"type":"string"},"description":"Short-lived connect token from the OAuth redirect"},{"name":"profileId","in":"query","required":true,"schema":{"type":"string"},"description":"Your Zernio profile ID"},{"name":"tempToken","in":"query","required":true,"schema":{"type":"string"},"description":"Temporary Snapchat access token from the OAuth callback redirect"}],"responses":{"200":{"description":"List of Snapchat Public Profiles available for connection","content":{"application/json":{"schema":{"type":"object","properties":{"publicProfiles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Snapchat Public Profile ID"},"display_name":{"type":"string","description":"Public profile display name"},"username":{"type":"string","description":"Public profile username/handle"},"profile_image_url":{"type":"string","description":"Profile image URL"},"subscriber_count":{"type":"integer","description":"Number of subscribers"}}}}}},"example":{"publicProfiles":[{"id":"abc123-def456","display_name":"My Brand","username":"mybrand","profile_image_url":"https://cf-st.sc-cdn.net/...","subscriber_count":15000},{"id":"xyz789-uvw012","display_name":"Side Project","username":"sideproject","profile_image_url":"https://cf-st.sc-cdn.net/...","subscriber_count":5000}]}}}},"400":{"description":"Missing required parameters (profileId or tempToken)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"No access to profile"},"500":{"description":"Failed to fetch public profiles"}}},"post":{"x-resource-group":"accounts","operationId":"selectSnapchatProfile","tags":["Connect"],"summary":"Select Snapchat profile","description":"Complete the Snapchat connection flow by saving the selected Public Profile. Snapchat requires a Public Profile to publish content. Use X-Connect-Token if connecting via API key.","parameters":[{"name":"X-Connect-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Short-lived connect token from the OAuth redirect (for API users)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","selectedPublicProfile","tempToken","userProfile"],"properties":{"profileId":{"type":"string","description":"Your Zernio profile ID"},"selectedPublicProfile":{"type":"object","description":"The selected Snapchat Public Profile","required":["id","display_name"],"properties":{"id":{"type":"string","description":"Snapchat Public Profile ID"},"display_name":{"type":"string","description":"Display name of the public profile"},"username":{"type":"string","description":"Username/handle"},"profile_image_url":{"type":"string","description":"Profile image URL"},"subscriber_count":{"type":"integer","description":"Number of subscribers"}}},"tempToken":{"type":"string","description":"Temporary Snapchat access token from OAuth"},"userProfile":{"type":"object","description":"User profile data from OAuth redirect"},"refreshToken":{"type":"string","description":"Snapchat refresh token (if available)"},"expiresIn":{"type":"integer","description":"Token expiration time in seconds"},"redirect_url":{"type":"string","format":"uri","description":"Custom redirect URL after connection completes"},"oauthAppId":{"type":"string","description":"The `oauthAppId` from the selection redirect, when the connect ran on one of your own OAuth apps. Pass it back so a retried selection stays on that app; a different app than the connect used returns 400."}}},"example":{"profileId":"64f0a1b2c3d4e5f6a7b8c9d0","selectedPublicProfile":{"id":"abc123-def456","display_name":"My Brand","username":"mybrand","profile_image_url":"https://cf-st.sc-cdn.net/...","subscriber_count":15000},"tempToken":"eyJ...","userProfile":{"id":"user123","username":"mybrand","displayName":"My Brand","profilePicture":"https://cf-st.sc-cdn.net/..."},"redirect_url":"https://yourapp.com/callback"}}}},"responses":{"200":{"description":"Snapchat Public Profile connected successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"redirect_url":{"type":"string","description":"Redirect URL with connection params (if provided in request)"},"account":{"type":"object","properties":{"accountId":{"type":"string","description":"ID of the created SocialAccount"},"platform":{"type":"string","enum":["snapchat"]},"username":{"type":"string"},"displayName":{"type":"string"},"profilePicture":{"type":"string"},"isActive":{"type":"boolean"},"publicProfileName":{"type":"string"}}}}},"example":{"message":"Snapchat connected successfully with public profile","redirect_url":"https://yourdomain.com/integrations/callback?connected=snapchat&profileId=507f1f77bcf86cd799439011&accountId=64e1f0a9e2b5af0012ab34cd&publicProfile=My+Brand","account":{"accountId":"64e1f0a9e2b5af0012ab34cd","platform":"snapchat","username":"mybrand","displayName":"My Brand","profilePicture":"https://cf-st.sc-cdn.net/...","isActive":true,"publicProfileName":"My Brand"}}}}},"400":{"description":"Missing required fields","content":{"application/json":{"example":{"error":"Missing required fields"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"No access to profile or profile limit exceeded","content":{"application/json":{"examples":{"forbidden":{"value":{"error":"Forbidden"}},"limitExceeded":{"value":{"error":"Cannot connect to this profile. It exceeds your Pro plan limit of 5 profiles.","code":"PROFILE_LIMIT_EXCEEDED"}},"betaRestricted":{"value":{"error":"Snapchat integration is currently in beta. Please wait until it is publicly released.","code":"PLATFORM_BETA_RESTRICTED"}}}}}},"500":{"description":"Failed to connect Snapchat account"}}}},"/v1/connect/bluesky/credentials":{"post":{"x-resource-group":"accounts","operationId":"connectBlueskyCredentials","tags":["Connect"],"summary":"Connect Bluesky account","description":"Connect a Bluesky account using identifier (handle or email) and an app password.\nTo get your userId for the state parameter, call GET /v1/users which includes a currentUserId field.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["identifier","appPassword","state"],"properties":{"identifier":{"type":"string","description":"Your Bluesky handle (e.g. user.bsky.social) or email address"},"appPassword":{"type":"string","description":"App password generated from Bluesky Settings > App Passwords"},"state":{"type":"string","description":"Required state formatted as {userId}-{profileId}. Get userId from GET /v1/users and profileId from GET /v1/profiles.","example":"6507a1b2c3d4e5f6a7b8c9d0-6507a1b2c3d4e5f6a7b8c9d1"},"redirect_url":{"type":"string","format":"uri","description":"Optional URL to redirect to after successful connection. Used when the state carries no redirect (a state minted by GET /v1/connect/bluesky with redirect_url already carries one, and that one wins)."},"redirectUri":{"type":"string","format":"uri","deprecated":true,"description":"Alias of redirect_url, kept for existing callers"}}},"example":{"identifier":"yourhandle.bsky.social","appPassword":"xxxx-xxxx-xxxx-xxxx","state":"6507a1b2c3d4e5f6a7b8c9d0-6507a1b2c3d4e5f6a7b8c9d1","redirect_url":"https://yourapp.com/connected"}}}},"responses":{"200":{"description":"Bluesky connected successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"account":{"$ref":"#/components/schemas/SocialAccount"}}},"example":{"message":"Bluesky connected successfully","account":{"platform":"bluesky","username":"yourhandle.bsky.social","displayName":"Your Name","isActive":true},"redirectUrl":"https://zernio.com/dashboard/profiles/64f0.../accounts"}}}},"400":{"description":"Invalid request - missing fields or invalid state format"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The connect token was issued for a different profile or platform (INSUFFICIENT_PERMISSIONS)."},"500":{"description":"Internal error"}}}},"/v1/connect/openai-ads/credentials":{"post":{"x-resource-group":"accounts","operationId":"connectOpenAIAdsCredentials","tags":["Connect"],"summary":"Connect an OpenAI Ads account","description":"Connect an OpenAI Ads account using an API key from ChatGPT Ads Manager.\n\nThe key grants full campaign write access on OpenAI's side (OpenAI does not offer a read-only key scope).\n\nZernio uses it to:\n\n- read ads and performance\n- create and manage campaigns you set up through Zernio (create, status, budget, and cancel)\n\nCampaigns created directly in ChatGPT Ads Manager can still be managed there.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["apiKey","profileId"],"properties":{"apiKey":{"type":"string","description":"API key from ChatGPT Ads Manager (Settings). Grants full read/write access on OpenAI's side; Zernio only ever reads with it."},"profileId":{"type":"string","description":"Your Zernio profile ID"},"state":{"type":"string","description":"Optional state passthrough for the connect flow."},"redirect_url":{"type":"string","format":"uri","description":"Optional URL to redirect to after successful connection, echoed back as redirectUrl."},"redirectUri":{"type":"string","format":"uri","deprecated":true,"description":"Alias of redirect_url, kept for existing callers"}}},"example":{"apiKey":"sk-ads-xxxxxxxxxxxxxxxxxxxx","profileId":"6507a1b2c3d4e5f6a7b8c9d0","redirect_url":"https://yourapp.com/connected"}}}},"responses":{"200":{"description":"OpenAI Ads connected successfully","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"},"adAccountName":{"type":"string"},"redirectUrl":{"type":"string"}}},"example":{"accountId":"6507a1b2c3d4e5f6a7b8c9d0","adAccountName":"Acme US"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Unauthorized, or the API key could not read an OpenAI ad account (code invalid_credentials)."},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"Ads add-on required."}}}},"/v1/connect/whop-ads/credentials":{"post":{"x-resource-group":"accounts","operationId":"connectWhopAdsCredentials","tags":["Connect"],"summary":"Connect a Whop account","description":"Connect a Whop account with an Account API key from the Whop dashboard (Developer >\nAPI keys). The key only has to be able to read its own account: Zernio calls\n`GET /accounts/me` once to learn the account id (`biz_...`) and name, then stores the key.\n\nWhat the connection unlocks today is the Whop Pixel through the tracking-tags API: the\naccount id is the pixel, so `GET /v1/accounts/{accountId}/tracking-tags` lists it and\n`POST .../tracking-tags/{biz_...}/install` puts it on a Shopify store or WordPress site.\nWhop campaigns are not managed through Zernio. One Whop account per profile.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["apiKey","profileId"],"properties":{"apiKey":{"type":"string","description":"Account API key from the Whop dashboard."},"profileId":{"type":"string","description":"Your Zernio profile ID"},"state":{"type":"string","description":"Optional state passthrough for the connect flow."},"redirect_url":{"type":"string","format":"uri","description":"Optional URL to redirect to after successful connection, echoed back as redirectUrl."}}},"example":{"apiKey":"whop_xxxxxxxxxxxxxxxxxxxx","profileId":"6507a1b2c3d4e5f6a7b8c9d0"}}}},"responses":{"200":{"description":"Whop account connected","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string","description":"The Zernio account id (platform `whopads`) to use as `{accountId}` on the tracking-tags routes."},"whopAccountId":{"type":"string","description":"The Whop account id (`biz_...`), which is also the tracking tag id."},"accountName":{"type":"string"},"redirectUrl":{"type":"string"}}},"example":{"accountId":"6507a1b2c3d4e5f6a7b8c9d0","whopAccountId":"biz_Ab3dEf9hJk2mN","accountName":"Shine Time Auto Detailing"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Unauthorized, or the API key could not read its Whop account (code invalid_credentials)."},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"Ads add-on required."},"409":{"description":"The profile already has a different Whop account connected (code PROFILE_PLATFORM_CONFLICT)."}}}},"/v1/connect/whatsapp/credentials":{"post":{"x-resource-group":"accounts","operationId":"connectWhatsAppCredentials","tags":["Connect"],"summary":"Connect WhatsApp via credentials","description":"Connect a WhatsApp Business Account by providing Meta credentials directly. This is the headless alternative to the Embedded Signup browser flow.\n\n### Getting the credentials\n\n1. Go to Meta Business Suite (business.facebook.com)\n2. Create or select a WhatsApp Business Account\n3. In Business Settings > System Users, create a System User\n4. Assign it the whatsapp_business_management and whatsapp_business_messaging permissions\n5. Generate a permanent access token\n6. Get the WABA ID from WhatsApp Manager > Account Tools > Phone Numbers\n7. Get the Phone Number ID from the same page (click on the number)\n\n### Warning: webhook delivery moves to Zernio\n\nConnecting subscribes your own Meta app to this WABA with an override callback that redirects its webhook delivery to Zernio.\n\nThis WABA's events stop reaching any callback URL you had configured before, immediately and with no overlap window.\n\nDo not unsubscribe your app from the WABA afterward: that also cuts off Zernio's delivery, and recovery requires calling this endpoint again.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","accessToken","wabaId","phoneNumberId"],"properties":{"profileId":{"type":"string","description":"Your Zernio profile ID"},"accessToken":{"type":"string","description":"Permanent System User access token from Meta Business Suite"},"wabaId":{"type":"string","description":"WhatsApp Business Account ID from Meta"},"phoneNumberId":{"type":"string","description":"Phone Number ID from Meta WhatsApp Manager"},"pin":{"type":"string","pattern":"^\\d{6}$","description":"The 6-digit two-step verification PIN set on the number. Required if you enabled two-step verification for it, otherwise Meta rejects the Cloud API registration with error 133005 and the number cannot send messages."},"oauthAppId":{"type":"string","description":"Your own WhatsApp OAuth app (see /v1/connect/oauth-apps) holding the Meta app the access token belongs to. The WABA's webhooks then go to that app's own callback URL and every delivery is checked against its app secret. Without it, deliveries come to Zernio's shared Meta webhook."}}},"example":{"profileId":"6507a1b2c3d4e5f6a7b8c9d0","accessToken":"EAABsbCS...your-system-user-token","wabaId":"123456789012345","phoneNumberId":"987654321098765","pin":"481902"}}}},"responses":{"200":{"description":"WhatsApp connected successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"registrationWarning":{"type":"string","description":"Present when the account was created but Meta rejected the Cloud API registration. The number cannot send messages until this is resolved."},"webhookNotice":{"type":"string","description":"Present when the WABA webhook subscription (with the Zernio override callback) succeeded. Explains the delivery cutover and warns against unsubscribing the app from the WABA afterward."},"account":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string","enum":["whatsapp"]},"username":{"type":"string","description":"Display phone number"},"displayName":{"type":"string","description":"Meta-verified business name"},"isActive":{"type":"boolean"},"phoneNumber":{"type":"string","description":"The connected phone number"},"verifiedName":{"type":"string","description":"Meta-verified business name for the phone number"},"qualityRating":{"type":"string","description":"Meta quality rating for the phone number (e.g. GREEN, YELLOW, RED, UNKNOWN)"}}}}},"example":{"message":"WhatsApp connected successfully","account":{"accountId":"6507a1b2c3d4e5f6a7b8c9d0","platform":"whatsapp","username":"+1 555-123-4567","displayName":"Acme Corp","isActive":true,"phoneNumber":"+1 555-123-4567","verifiedName":"Acme Corp","qualityRating":"GREEN"}}}}},"400":{"x-summary":"The request is invalid, like missing fields, a PIN that is not 6 digits, or an unknown phone number ID: fix it.","description":"Invalid request. Missing fields, a `pin` that is not 6 digits, or the\nphoneNumberId was not found in the specified WABA. If the phone was not\nfound, the response includes availablePhoneNumbers to help identify the\ncorrect ID.\n"},"401":{"description":"Invalid or expired access token"},"403":{"description":"Profile limit exceeded for this plan"},"409":{"x-summary":"The number is already tied to another profile and can only be live on one: connect it there or disconnect it first.","description":"Conflict with an existing connection. A number can only be live on one profile. Cases:\n\n- WHATSAPP_NUMBER_PINNED_TO_PROFILE: a Zernio-provisioned number pinned to a different profile. Connect it from that profile, or move it first with PATCH /v1/whatsapp/phone-numbers/{id}/profile.\n- WHATSAPP_NUMBER_ALREADY_CONNECTED: already actively connected on another profile or team. Disconnect it there first.\n- WHATSAPP_COEXISTENCE_NOT_REGISTERED: a number connected from the WhatsApp Business app (coexistence) that the phone never registered on the Cloud API, so Meta reported platform_type ON_PREMISE and refused the contacts/history sync with error 133010.\n\nIn the coexistence case no account is created. The customer opens WhatsApp Business on the phone, keeps it open and updated, and runs the same Embedded Signup again, which succeeds on the second attempt in practice.\n"}}}},"/v1/connect/whatsapp/select-phone-number":{"get":{"x-resource-group":"accounts","operationId":"listWhatsAppPhoneNumbers","tags":["Connect"],"summary":"List numbers for selection","description":"Fetch the WhatsApp phone numbers available across the user's WhatsApp Business Accounts (WABAs) after a headless OAuth flow.\n\nWhatsApp OAuth grants access at the WABA level. When a connected WABA has 2 or more phone numbers, you must call this endpoint to list them and then `POST /v1/connect/whatsapp/select-phone-number` to bind one to the Zernio profile. Single-phone WABAs auto-complete during the OAuth callback and never reach this endpoint.\n\nUse the `profileId` and `tempToken` returned in the headless redirect (`step=select_phone_number`).\n\nAlternative: if you already know `wabaId` and `phoneNumberId` (e.g. from Meta Business Suite), use `connectWhatsAppCredentials` instead, which skips this two-step flow.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"profileId","in":"query","required":true,"schema":{"type":"string"},"description":"The Zernio profile ID from the headless redirect"},{"name":"tempToken","in":"query","required":true,"schema":{"type":"string"},"description":"The temporary access token from the headless redirect"},{"name":"X-Connect-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Alternative auth for API users' end customers (used when the bearer token is scoped to a different user)"}],"responses":{"200":{"description":"Phone numbers fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumbers":{"type":"array","items":{"type":"object","description":"Phone number entry. Field names use Meta WhatsApp Cloud API snake_case (passed through unchanged); wabaId and wabaName are Zernio enrichment.","properties":{"id":{"type":"string","description":"Phone Number ID (Meta)"},"display_phone_number":{"type":"string","description":"E.164-formatted display number"},"verified_name":{"type":"string","description":"Meta-verified business name"},"quality_rating":{"type":"string","description":"GREEN, YELLOW, RED, or UNKNOWN"},"name_status":{"type":"string","description":"APPROVED, PENDING_REVIEW, DECLINED, or NONE"},"messaging_limit_tier":{"type":"string","description":"TIER_250, TIER_1K, TIER_10K, TIER_100K, or TIER_UNLIMITED"},"wabaId":{"type":"string","description":"WhatsApp Business Account ID (Zernio enrichment)"},"wabaName":{"type":"string","description":"WABA display name (Zernio enrichment)"}}}}}},"example":{"phoneNumbers":[{"id":"1875844705851813","display_phone_number":"+55 83 8793-2039","verified_name":"Bioface","quality_rating":"GREEN","name_status":"APPROVED","messaging_limit_tier":"TIER_1K","wabaId":"317766992490131","wabaName":"Bioface WABA"}]}}}},"400":{"description":"Missing profileId or tempToken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to fetch phone numbers (Meta API error, expired token, or insufficient permissions)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"x-resource-group":"accounts","operationId":"completeWhatsAppPhoneSelection","tags":["Connect"],"summary":"Complete number selection","description":"Bind a specific WhatsApp phone number to the Zernio profile after the user picks one from `listWhatsAppPhoneNumbers`. Exchanges the short-lived OAuth token for a long-lived token, subscribes the WABA to webhooks, and creates the SocialAccount.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"X-Connect-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Alternative auth for API users' end customers"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","phoneNumberId","wabaId","tempToken"],"properties":{"profileId":{"type":"string","description":"The Zernio profile ID"},"phoneNumberId":{"type":"string","description":"The selected phone number ID (from listWhatsAppPhoneNumbers)"},"wabaId":{"type":"string","description":"The WABA ID containing the selected phone"},"tempToken":{"type":"string","description":"The temporary access token from the headless redirect"},"userProfile":{"type":"object","description":"Optional user profile data (passthrough)"},"redirect_url":{"type":"string","description":"Optional URL to receive the post-connection redirect target"}}},"example":{"profileId":"6507a1b2c3d4e5f6a7b8c9d0","phoneNumberId":"1875844705851813","wabaId":"317766992490131","tempToken":"EAABsbCS...short-lived-token"}}}},"responses":{"200":{"description":"Phone number connected successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"redirect_url":{"type":"string","description":"Present only if redirect_url was provided in the request"},"account":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string","enum":["whatsapp"]},"username":{"type":"string","description":"Display phone number"},"displayName":{"type":"string","description":"Meta-verified business name"},"isActive":{"type":"boolean"},"selectedPhoneNumber":{"type":"string"}}}}},"example":{"message":"WhatsApp phone number connected successfully","account":{"accountId":"6507a1b2c3d4e5f6a7b8c9d0","platform":"whatsapp","username":"+55 83 8793-2039","displayName":"Bioface","isActive":true,"selectedPhoneNumber":"+55 83 8793-2039"}}}}},"400":{"description":"Missing required fields (profileId, phoneNumberId, wabaId, or tempToken)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Profile limit exceeded for the user's plan (PROFILE_LIMIT_EXCEEDED)"},"404":{"description":"Selected phone number not found in the specified WABA","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"x-summary":"The number is already tied to another profile and can only be live on one: connect it there or disconnect it first.","description":"Conflict with an existing connection. A number can only be live on one profile. One of:\n\n- **WHATSAPP_NUMBER_PINNED_TO_PROFILE:** the number is a Zernio-provisioned number pinned to a different profile. Connect it from that profile, or move it first with PATCH /v1/whatsapp/phone-numbers/{id}/profile.\n- **WHATSAPP_NUMBER_ALREADY_CONNECTED:** the number is already actively connected on another profile or team. Disconnect it there first.\n- **WHATSAPP_COEXISTENCE_NOT_REGISTERED:** for a number connected from the WhatsApp Business app (coexistence), the phone never registered the number on the Cloud API. Meta reported it as platform_type ON_PREMISE and refused the contacts/history sync with error 133010.\n\nIn the coexistence case no account is created. The customer opens WhatsApp Business on the phone, keeps it open and updated, and runs the same Embedded Signup again, which in practice succeeds on the second attempt.\n"},"500":{"description":"Failed to bind phone number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/connect/whatsapp/embedded-signup":{"post":{"x-resource-group":"accounts","operationId":"connectWhatsAppEmbeddedSignup","tags":["Connect"],"summary":"Connect WhatsApp from Embedded Signup","description":"Exchange the authorization code Meta's Embedded Signup popup returned.\n\nThis is the call the Zernio-hosted signup page makes after the popup closes (`GET /v1/connect/whatsapp?signup=hosted`). It sends the `wabaId` and `phoneNumberId` Meta reported, so exactly the chosen number is connected. When both are omitted, the first number the token can see is used.\n\nThe code never passes through a `redirect_uri`, so `POST /v1/connect/{platform}` cannot accept it.\n\nAuthenticates with an API key, or with the connect token the hosted flow issues (`X-Connect-Token` header).\n","parameters":[{"name":"X-Connect-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Connect token issued by the hosted signup flow, accepted instead of an API key."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","profileId"],"properties":{"code":{"type":"string","description":"Authorization code from the WA_EMBEDDED_SIGNUP postMessage"},"profileId":{"type":"string"},"wabaId":{"type":"string","description":"WhatsApp Business Account id, when the SDK reported one"},"phoneNumberId":{"type":"string"},"isCoexistence":{"type":"boolean","description":"Number is also live in the WhatsApp Business app"},"expectedPhoneNumber":{"type":"string","description":"Rejects the connect when Meta returns a different number"},"redirect_url":{"type":"string","description":"Hosted signup page only. When present, the response also carries `redirectUrl`, the URL the user should land on, with the outcome mapped exactly like the redirect flow (success params, or `error` and `platform` with the same values).\n\nMust be an absolute http(s) URL or a custom app scheme. The legacy spelling `redirectUrl` remains accepted as an alias.\n"},"echoConnectToken":{"type":"boolean","description":"Hosted signup page only. Append the connect token to the success redirect, as the redirect flow does for API-key callers."}}}}}},"responses":{"200":{"description":"Number connected","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"account":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string","enum":["whatsapp"]},"username":{"type":"string"},"displayName":{"type":"string"},"isActive":{"type":"boolean"},"selectedPhoneNumber":{"type":"string"}}},"redirectUrl":{"type":"string","description":"Present only when `redirect_url` was sent; also present on error responses."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"409":{"description":"The number is already connected on another profile or team"}}}},"/v1/connect/whatsapp/sdk-config":{"get":{"x-resource-group":"accounts","operationId":"getWhatsAppSdkConfig","tags":["Connect"],"summary":"Get Embedded Signup SDK config","description":"Returns the Meta app id and Embedded Signup configuration id the Zernio-hosted signup page uses to open Meta's popup.\n\nIntegrators do not need this endpoint: start the hosted flow with `GET /v1/connect/whatsapp?signup=hosted` and send the user to the returned `authUrl`.\n\nAuthenticates with an API key or with the connect token the hosted flow issues (`X-Connect-Token` header).\n","parameters":[{"name":"X-Connect-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Connect token issued by the hosted signup flow, accepted instead of an API key."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Meta app configuration for Embedded Signup","content":{"application/json":{"schema":{"type":"object","required":["appId","configId","branding"],"properties":{"appId":{"type":"string","description":"Meta app id"},"configId":{"type":"string","description":"Embedded Signup configuration id"},"branding":{"type":["object","null"],"description":"Skin chosen when the hosted signup session was issued (`brandName`, `primaryColor`, `language` on `GET /v1/connect/whatsapp?signup=hosted`). Null for API-key callers and for sessions issued without one.","properties":{"brandName":{"type":["string","null"]},"primaryColor":{"type":["string","null"],"description":"Hex colour, #RRGGBB"},"language":{"type":["string","null"],"enum":["en","es","pt-BR",null]}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/connect/discord":{"post":{"x-resource-group":"accounts","operationId":"connectDiscordChannel","tags":["Connect"],"summary":"Connect a Discord channel","description":"Finalize a Discord connect by binding channels to a profile. Served by a dedicated route, so it is not reachable through POST /v1/connect/{platform}. One connected account per channel: send channelIds to connect several channels of the server at once, or repeat the call with a different channelId.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["guildId","profileId"],"properties":{"guildId":{"type":"string","description":"Discord server (guild) the channel belongs to"},"channelId":{"type":"string","description":"Text, announcement or forum channel to publish to. Send this or channelIds, not both."},"channelIds":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string"},"description":"Several channels of the server to connect, each as its own account. With two or more distinct ids the response lists `accounts` and `failed` instead of `account`. A single id behaves exactly like channelId."},"profileId":{"type":"string","description":"Profile to connect the channel to"},"redirect_url":{"type":"string","description":"channelIds only: a URL to return in `redirect_url`, with `connected`, `profileId`, `accountId` and `accountIds` appended."}}}}}},"responses":{"200":{"description":"Channel connected"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"The connect token was issued for a different profile or platform (INSUFFICIENT_PERMISSIONS)."},"404":{"description":"Profile not found"},"422":{"x-summary":"None of the selected channels could be connected: read `details.failed` for each reason and fix them.","description":"channelIds only. None of the channels could be connected; `details.failed` lists each one with its reason.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/connect/slack":{"get":{"x-resource-group":"accounts","operationId":"listSlackChannels","tags":["Connect"],"summary":"List Slack channels for the channel picker","description":"Serves the channel picker of the Slack connect flow. Slack's OAuth installs the bot into a workspace, not a channel, so after the redirect the caller lists the workspace's channels here and finalizes one with `POST /v1/connect/slack`.\n\nServed by a dedicated route that shadows `GET /v1/connect/{platform}` for `slack`.\n\n### Parameters\n\nSend exactly one of:\n\n- `pendingDataToken`: first connect. The nonce from the OAuth redirect, bound to the same `profileId`.\n- `accountId`: add another channel to a workspace already connected. The existing Slack account's workspace token is reused, no re-OAuth.\n\nWith neither, the endpoint behaves like `GET /v1/connect/{platform}` and returns `authUrl` and `state` to start the OAuth flow.\n\n### Channels\n\nChannels are read live from Slack (`conversations.list`, public and private, archived excluded, up to 2,000).\n\n`isMember` says whether the Zernio bot is already in the channel. A public channel is joined automatically on finalize; a private one must be invited (`/invite @Zernio`) first.\n","parameters":[{"name":"profileId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio profile the channel account will belong to. Must match the profile the OAuth flow was started on when `pendingDataToken` is used."},{"name":"pendingDataToken","in":"query","schema":{"type":"string","minLength":16},"description":"Nonce from the OAuth redirect (first connect)."},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Existing active Slack account (yours or a team member's) whose workspace token is reused."},{"name":"redirect_url","in":"query","schema":{"type":"string","format":"uri"},"description":"Start-OAuth mode only: where to send the user after the connect completes. `redirectUrl` is accepted as an alias."},{"name":"scopes","in":"query","schema":{"type":"string","example":"posting"},"description":"Start-OAuth mode only. Comma-separated permission areas to request instead of the full Slack scope set, same semantics as `scopes` on `GET /v1/connect/{platform}`. Omit it to request everything.\n\n- `posting`: installs the bot with the channel scopes it needs to post.\n- `messaging`: adds the history, DM and reaction scopes the inbox reads.\n- `analytics`, `comments`, `ads`: add nothing on Slack.\n"}],"responses":{"200":{"description":"Channel list (picker mode), or the OAuth URL when neither `pendingDataToken` nor `accountId` is sent","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Channel picker","required":["team","channels"],"properties":{"team":{"type":"object","properties":{"id":{"type":"string","description":"Slack workspace (team) id"},"name":{"type":["string","null"]},"icon":{"type":["string","null"],"format":"uri","description":"Workspace icon URL"}}},"channels":{"type":"array","items":{"type":"object","required":["id","name","isPrivate","isMember"],"properties":{"id":{"type":"string","description":"Channel id (C... or G...), the value to send as channelId on POST"},"name":{"type":"string"},"isPrivate":{"type":"boolean"},"isMember":{"type":"boolean","description":"Whether the Zernio bot is already a member of the channel"}}}}}},{"type":"object","title":"Start OAuth","required":["authUrl","state"],"properties":{"authUrl":{"type":"string","format":"uri"},"state":{"type":"string"}}}]},"examples":{"picker":{"value":{"team":{"id":"T0123ABCD","name":"Acme","icon":"https://avatars.slack-edge.com/acme_88.png"},"channels":[{"id":"C0123ABCD","name":"general","isPrivate":false,"isMember":true},{"id":"G0456EFGH","name":"leadership","isPrivate":true,"isMember":false}]}},"startOAuth":{"value":{"authUrl":"https://slack.com/oauth/v2/authorize?client_id=...&state=...","state":"user123-profile456-1234567890-https%3A%2F%2Fzernio.com%2Fdashboard%2Fconnections"}}}}}},"400":{"description":"Invalid profileId or accountId format, or pendingDataToken invalid, expired or issued for another profile (code: invalid_field_value)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The key has no access to the profile, Slack is temporarily unavailable, or the connect token is for another profile: check both.","description":"No access to the profile, or Slack connections are temporarily unavailable (code: feature_not_available), or the connect token was issued for a different profile or platform (INSUFFICIENT_PERMISSIONS)"},"404":{"description":"Profile not found (start-OAuth mode), or no active Slack account with that accountId for this user or their team (code: account_not_found)"}}},"post":{"x-resource-group":"accounts","operationId":"connectSlackChannel","tags":["Connect"],"summary":"Connect a Slack channel","description":"Finalize a Slack connect by creating the per-channel account. Served by a dedicated route, so it is not reachable through POST /v1/connect/{platform}. Send pendingDataToken for a first connect (the nonce from the OAuth redirect) or accountId to add another channel to a workspace already connected.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId"],"properties":{"profileId":{"type":"string"},"channelId":{"type":"string","description":"Slack channel id, C... or G.... Send this or channelIds, not both."},"channelIds":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string"},"description":"Several channels of the workspace to connect, each as its own account. With two or more distinct ids the response lists `accounts` and `failed` instead of `account`, and the request is refused with 400 on a reconnect. A single id behaves exactly like channelId."},"redirect_url":{"type":"string","description":"channelIds only: a URL to return in `redirect_url`, with `connected`, `profileId`, `accountId` and `accountIds` appended."},"pendingDataToken":{"type":"string","description":"Nonce from the OAuth redirect. Required unless accountId is sent."},"accountId":{"type":"string","description":"Existing Slack account whose workspace token is reused. Required unless pendingDataToken is sent."}}}}}},"responses":{"200":{"description":"Channel connected"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"x-summary":"Slack connections are unavailable or the connect token is for another profile or platform: retry later or get a new token.","description":"Slack connections are temporarily unavailable, or the connect token was issued for a different profile or platform (INSUFFICIENT_PERMISSIONS)"},"404":{"description":"Profile not found"},"422":{"x-summary":"None of the selected channels could be connected: read `details.failed` for each reason and fix them.","description":"channelIds only. None of the channels could be connected; `details.failed` lists each one with its reason.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/connect/telegram":{"get":{"x-resource-group":"accounts","operationId":"getTelegramConnectStatus","tags":["Connect"],"summary":"Generate Telegram code","description":"Generate an access code (valid 15 minutes) for connecting a Telegram channel or group. Add the bot as admin, then send the code + @yourchannel to the bot. Poll PATCH /v1/connect/telegram to check status.","parameters":[{"name":"profileId","in":"query","required":true,"schema":{"type":"string"},"description":"The profile ID to connect the Telegram account to"}],"responses":{"200":{"description":"Access code generated","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The access code to send to the Telegram bot","example":"ZRN-ABC123"},"expiresAt":{"type":"string","format":"date-time","description":"When the code expires"},"expiresIn":{"type":"integer","description":"Seconds until expiration","example":900},"botUsername":{"type":"string","description":"The Telegram bot username to message","example":"LateScheduleBot"},"instructions":{"type":"array","items":{"type":"string"},"description":"Step-by-step connection instructions"}}},"example":{"code":"ZRN-ABC123","expiresAt":"2024-01-15T12:30:00.000Z","expiresIn":900,"botUsername":"LateScheduleBot","instructions":["1. Add @ZernioScheduleBot as an administrator in your channel/group","2. Open a private chat with @ZernioScheduleBot","3. Send: ZRN-ABC123 @yourchannel (replace @yourchannel with your channel username)","4. Wait for confirmation - the connection will appear in your dashboard","Tip: If your channel has no public username, forward a message from it along with the code"]}}}},"400":{"description":"Profile ID required or invalid format"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"No access to this profile, or the connect token was issued for a different profile or platform (INSUFFICIENT_PERMISSIONS)"},"404":{"description":"Profile not found"},"500":{"description":"Internal error"}}},"post":{"x-resource-group":"accounts","operationId":"initiateTelegramConnect","tags":["Connect"],"summary":"Connect Telegram directly","description":"Connect a Telegram channel/group directly using the chat ID. Alternative to the access code flow. The bot must already be an admin in the channel/group.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chatId","profileId"],"properties":{"chatId":{"type":"string","description":"The Telegram chat ID. Numeric ID (e.g. \"-1001234567890\") or username with @ prefix (e.g. \"@mychannel\")."},"profileId":{"type":"string","description":"The profile ID to connect the account to"}}},"example":{"chatId":"-1001234567890","profileId":"6507a1b2c3d4e5f6a7b8c9d0"}}}},"responses":{"200":{"description":"Telegram channel connected successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"account":{"type":"object","properties":{"_id":{"type":"string"},"platform":{"type":"string","enum":["telegram"]},"username":{"type":"string"},"displayName":{"type":"string"},"isActive":{"type":"boolean"},"chatType":{"type":"string","enum":["channel","group","supergroup","private"]}}}}},"example":{"message":"Telegram channel connected successfully","account":{"_id":"64e1f0a9e2b5af0012ab34cd","platform":"telegram","username":"mychannel","displayName":"My Channel","isActive":true,"chatType":"channel"}}}}},"400":{"description":"Chat ID required, bot not admin, or cannot access chat"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"No access to this profile, or the connect token was issued for a different profile or platform (INSUFFICIENT_PERMISSIONS)"},"404":{"description":"Profile not found"},"500":{"description":"Internal error"}}},"patch":{"x-resource-group":"accounts","operationId":"completeTelegramConnect","tags":["Connect"],"summary":"Check Telegram status","description":"Poll this endpoint to check if a Telegram access code has been used to connect a channel/group. Recommended polling interval: 3 seconds.\nStatus values: pending (waiting for user), connected (channel/group linked), expired (generate a new code).\n","parameters":[{"name":"code","in":"query","required":true,"schema":{"type":"string"},"description":"The access code to check status for","example":"ZRN-ABC123"}],"responses":{"200":{"description":"Connection status","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Pending","properties":{"status":{"type":"string","enum":["pending"]},"expiresAt":{"type":"string","format":"date-time"},"expiresIn":{"type":"integer","description":"Seconds until expiration"}}},{"type":"object","title":"Connected","properties":{"status":{"type":"string","enum":["connected"]},"chatId":{"type":"string"},"chatTitle":{"type":"string"},"chatType":{"type":"string","enum":["channel","group","supergroup"]},"account":{"type":"object","properties":{"_id":{"type":"string"},"platform":{"type":"string"},"username":{"type":"string"},"displayName":{"type":"string"}}}}},{"type":"object","title":"Expired","properties":{"status":{"type":"string","enum":["expired"]},"message":{"type":"string"}}}]},"examples":{"pending":{"summary":"Waiting for connection","value":{"status":"pending","expiresAt":"2024-01-15T12:30:00.000Z","expiresIn":542}},"connected":{"summary":"Successfully connected","value":{"status":"connected","chatId":"-1001234567890","chatTitle":"My Channel","chatType":"channel","account":{"_id":"64e1f0a9e2b5af0012ab34cd","platform":"telegram","username":"mychannel","displayName":"My Channel"}}},"expired":{"summary":"Code expired","value":{"status":"expired","message":"Access code has expired. Please generate a new one."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The connect token was issued for a different profile or platform (INSUFFICIENT_PERMISSIONS)."},"404":{"description":"Code not found"},"500":{"description":"Internal error"}}}},"/v1/accounts/{accountId}/webhook-subscription":{"get":{"x-resource-group":"accounts","operationId":"getPageWebhookSubscription","tags":["Connect"],"summary":"Read a Facebook Page's webhook subscription","description":"Returns the webhook fields Zernio's app is subscribed to on the connected Page, read live from Meta.\nUse it to confirm `leadgen` is present: a Page missing it keeps delivering every other event while\nlead ads stop arriving, with nothing to indicate it.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The Page's current subscription","content":{"application/json":{"schema":{"type":"object","properties":{"pageId":{"type":"string"},"appSubscribed":{"type":"boolean","description":"False when the Page carries no subscription for our app at all."},"leadgen":{"type":"boolean","description":"Whether lead ads submitted on this Page reach Zernio in real time."},"subscribedFields":{"type":"array","items":{"type":"string"}},"warning":{"type":["string","null"],"description":"Present only when leadgen is missing."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The connection has no selected Page"}}},"post":{"x-resource-group":"accounts","operationId":"resyncPageWebhookSubscription","tags":["Connect"],"summary":"Re-subscribe a Facebook Page to Zernio's webhooks","description":"Re-sends the full field set to Meta and returns the subscription read back afterwards.\nMeta only honours the field set sent at subscribe time, so a Page connected before a field\nexisted stays without it until this runs. The response reflects what Meta actually granted,\nnot what was requested.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The subscription after re-subscribing","content":{"application/json":{"schema":{"type":"object","properties":{"resubscribed":{"type":"boolean"},"pageId":{"type":"string"},"appSubscribed":{"type":"boolean"},"leadgen":{"type":"boolean"},"subscribedFields":{"type":"array","items":{"type":"string"}},"warning":{"type":["string","null"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The connection has no selected Page"},"502":{"description":"Meta rejected the subscription"}}}},"/v1/accounts/{accountId}/business-partners":{"get":{"x-resource-group":"accounts","operationId":"listBusinessPartners","tags":["Accounts"],"x-platforms":["facebook","instagram"],"summary":"List partner businesses of the Page","description":"The business portfolios (Meta Business Managers) that may act on the Facebook Page\nbehind this account, plus the Page's owning portfolio and linked Instagram\nprofessional account. Works on Facebook accounts and on Instagram accounts connected\nthrough Facebook Login.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id of the Facebook or Instagram account."}],"responses":{"200":{"description":"Page ownership and partners","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"$ref":"#/components/schemas/MetaPageOwnership"},"partners":{"type":"array","items":{"$ref":"#/components/schemas/MetaPagePartner"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Meta refused because the connecting user lacks business management permission or is not an admin of the owning portfolio: reconnect the account.","description":"Meta refused: the connecting user lacks business_management or is not an admin of the owning portfolio. Reconnect the account."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"422":{"description":"No Facebook Page is linked (Instagram Login account, or no Page selected)."},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"x-resource-group":"accounts","operationId":"grantBusinessPartner","tags":["Accounts"],"x-platforms":["facebook","instagram"],"summary":"Share the Page with a partner business","description":"Grants a partner business portfolio tasks on the Facebook Page behind this account.\n\nWith `ADVERTISE`, the partner can run ads for the Page from ad accounts in its own portfolio. This is how an integrator advertises for an end user without touching the end user's ad accounts.\n\n### Responses\n\n- `422`: the Page is outside any business portfolio. Meta only lets a user token share a Page that a portfolio owns, so claim it into one at business.facebook.com first.\n- `200` with `alreadyShared: true` and the tasks the partner currently holds: the portfolio already has access. Meta refuses a second grant instead of replacing its tasks.\n\nTo change a partner's tasks, revoke and grant again.\n\n### After the grant\n\nThe partner assigns its own people to the Page with `POST /v1/ads/page-users`; Meta does not assign partner admins automatically.\n\nThe Instagram professional account linked to the Page is returned in `page` so the partner can reference it. Meta exposes no API to share Instagram accounts; that is done in Business Settings.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id of the Facebook or Instagram account."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["businessId"],"properties":{"businessId":{"type":"string","description":"Meta business portfolio id of the partner (numeric string)."},"permittedTasks":{"type":"array","description":"Tasks granted on the Page, Meta's permitted_tasks vocabulary. Defaults to ADVERTISE and ANALYZE. The bare names are what Business Settings shows; the PROFILE_PLUS_ names are the New Pages Experience tasks and the only way to grant FACEBOOK_ACCESS or REVENUE. Granting MANAGE also yields MANAGE_LEADS.","items":{"type":"string","enum":["MANAGE","CREATE_CONTENT","MODERATE","MESSAGING","ADVERTISE","ANALYZE","MODERATE_COMMUNITY","MANAGE_JOBS","PAGES_MESSAGING","PAGES_MESSAGING_SUBSCRIPTIONS","READ_PAGE_MAILBOXES","VIEW_MONETIZATION_INSIGHTS","MANAGE_LEADS","CASHIER_ROLE","GLOBAL_STRUCTURE_MANAGEMENT","PROFILE_PLUS_FULL_CONTROL","PROFILE_PLUS_MANAGE","PROFILE_PLUS_FACEBOOK_ACCESS","PROFILE_PLUS_CREATE_CONTENT","PROFILE_PLUS_MODERATE","PROFILE_PLUS_MODERATE_DELEGATE_COMMUNITY","PROFILE_PLUS_MESSAGING","PROFILE_PLUS_ADVERTISE","PROFILE_PLUS_ANALYZE","PROFILE_PLUS_REVENUE","PROFILE_PLUS_MANAGE_LEADS","PROFILE_PLUS_CREATIVE_MANAGEMENT","PROFILE_PLUS_CREATOR_MANAGEMENT","PROFILE_PLUS_GLOBAL_STRUCTURE_MANAGEMENT"]}}}},"example":{"businessId":"1234567890123","permittedTasks":["ADVERTISE","ANALYZE"]}}}},"responses":{"200":{"description":"The portfolio already had access; nothing changed","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"$ref":"#/components/schemas/MetaPageOwnership"},"partner":{"type":"object","properties":{"businessId":{"type":"string"},"permittedTasks":{"type":"array","items":{"type":"string"},"description":"Tasks the partner currently holds."}}},"alreadyShared":{"type":"boolean","description":"Always true on this response."}}}}}},"201":{"description":"Page shared","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"$ref":"#/components/schemas/MetaPageOwnership"},"partner":{"type":"object","properties":{"businessId":{"type":"string"},"permittedTasks":{"type":"array","items":{"type":"string"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Meta refused because the connecting user lacks business management permission or is not an admin of the owning portfolio: reconnect the account.","description":"Meta refused: the connecting user lacks business_management or is not an admin of the owning portfolio. Reconnect the account."},"404":{"description":"Account not found, or Meta could not load the partner business."},"422":{"description":"The Page is not owned by a business portfolio, or no Page is linked to the account."},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"x-resource-group":"accounts","operationId":"revokeBusinessPartner","tags":["Accounts"],"x-platforms":["facebook","instagram"],"summary":"Revoke a partner business from the Page","description":"Removes every task the partner business portfolio held on the Page.","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id of the Facebook or Instagram account."},{"name":"businessId","in":"query","required":true,"schema":{"type":"string"},"description":"Meta business portfolio id of the partner (numeric string)."}],"responses":{"200":{"description":"Access revoked","content":{"application/json":{"schema":{"type":"object","properties":{"pageId":{"type":"string"},"businessId":{"type":"string"},"revoked":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Meta refused: the connecting user lacks business_management or is not an admin of the owning portfolio."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"422":{"description":"No Facebook Page is linked to the account."},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/accounts/{accountId}/facebook-page":{"get":{"x-resource-group":"accounts","operationId":"getFacebookPages","tags":["Connect"],"summary":"List Facebook pages","description":"Returns all Facebook Pages the connected account has access to, including the currently selected Page and the Instagram professional account linked to each Page.\n\nWorks on `facebook` accounts and on `metaads` accounts (classic and Facebook Login for Business connections).\n\n- Business-login `metaads` connection: `selectedPageId` is the default Page ads run as, and every listed Page can be passed as `pageId` on POST /v1/ads/create.\n- Classic `metaads` connection: there is no default Page, so `selectedPageId` is null.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"refresh","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true, bypasses the page cache and fetches fresh pages from Meta. Rate-limited server-side to 1 refresh per 60s. Pages no longer accessible to the connected account will be removed from the list on refresh.\n"}],"responses":{"200":{"description":"Pages list","content":{"application/json":{"schema":{"type":"object","properties":{"pages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"username":{"type":"string"},"category":{"type":"string"},"fan_count":{"type":"integer"},"instagramAccount":{"type":["object","null"],"description":"The Instagram professional account linked to the Page (Meta instagram_business_account), or null when none is linked or the list was served from a cache stored before this field existed (pass refresh=true to re-read it).","properties":{"id":{"type":"string","description":"Instagram professional account id, usable as instagramAccountId on POST /v1/ads/create"},"username":{"type":["string","null"]}}}}}},"selectedPageId":{"type":["string","null"]},"cached":{"type":"boolean","description":"false when this response was just read from Meta (cold cache or a refresh that ran), true when served from the stored list (including a debounced refresh or an empty Meta answer)"}}},"example":{"pages":[{"id":"123456789012345","name":"My Brand Page","username":"mybrand","category":"Brand","fan_count":5000,"instagramAccount":{"id":"17841400000000000","username":"mybrand"}},{"id":"234567890123456","name":"My Other Page","username":"myotherpage","category":"Business","fan_count":1200,"instagramAccount":null}],"selectedPageId":"123456789012345","cached":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found, or not a facebook or metaads account"}}},"put":{"x-resource-group":"accounts","operationId":"updateFacebookPage","tags":["Connect"],"summary":"Update Facebook page","description":"Switch which Facebook Page is active for a connected account.\n\n- `facebook` account: changes the Page posts publish to.\n- Facebook Login for Business `metaads` connection: changes the default Page ads run as (and the Page whose leads are ingested).\n- Classic `metaads` connection: has no default Page and answers 400. Pass `pageId` per ad on POST /v1/ads/create instead.\n\nThe Page must be in the list returned by GET (use refresh=true to pick up newly granted Pages).\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["selectedPageId"],"properties":{"selectedPageId":{"type":"string"}}},"example":{"selectedPageId":"123456789012345"}}}},"responses":{"200":{"description":"Page updated","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"selectedPage":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}},"example":{"message":"Facebook page updated successfully","selectedPage":{"id":"123456789012345","name":"My Brand Page"}}}}},"400":{"description":"Page not in available pages, missing selectedPageId, or a classic metaads connection (no default Page)"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found, or not a facebook or metaads account"},"409":{"x-summary":"Another account on this profile already uses that destination, or the Page has no stored token: choose another destination or reconnect.","description":"Another account on this profile is already connected to that destination (profile_platform_conflict), or the Page has no stored access token (reconnect_required).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/accounts/{accountId}/facebook-page-info":{"get":{"x-resource-group":"accounts","operationId":"getFacebookPageInfo","tags":["Account Settings"],"summary":"Get a Facebook Page's public info","description":"Returns the public info of the Page selected on a `facebook` account: about,\ndescription, website, phone, emails and opening hours, as Meta returns them\nfrom the Page node. Text fields the Page never filled come back as null.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"description":"The ID of a connected Facebook account.","schema":{"type":"string"}}],"responses":{"200":{"description":"The Page's public info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacebookPageInfo"}}}},"400":{"description":"Invalid accountId, an account on another platform (`platform_not_supported`), or Meta refused the request (`platform_api_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is not scoped to this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The account is not reachable by the caller (`account_not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"x-summary":"The connection has no Facebook Page selected: select a Page or reconnect the account.","description":"The connection has no Facebook Page selected (`linked_account_required`). Select a Page or reconnect the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"x-resource-group":"accounts","operationId":"updateFacebookPageInfo","tags":["Account Settings"],"summary":"Update a Facebook Page's public info","description":"Updates the public info of the Page selected on a `facebook` account. Only the\nfields in the body are sent to Meta, every other field keeps its value. Send an\nempty string to clear a text field. Unknown fields are rejected with a 400.\n\nReturns the Page info read back from Meta after the update. Meta needs the\n`pages_manage_metadata` permission and a Page role that can edit the Page:\nwithout them Meta's refusal comes back as `platform_api_error`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"description":"The ID of a connected Facebook account.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"about":{"type":"string","maxLength":100,"description":"Short description, shown as Description in the Page's Edit Page Info."},"description":{"type":"string","description":"Longer text, shown as Additional Information."},"website":{"type":"string","description":"URL of the Page's website."},"phone":{"type":"string"},"emails":{"type":"array","description":"Replaces every email listed on the Page.","items":{"type":"string","format":"email"}},"hours":{"type":"object","description":"Replaces the opening hours. Keys are `{day}_{slot}_{open|close}` with day `mon` to `sun` and slot 1 or 2, values are 24h `HH:MM` times.","propertyNames":{"pattern":"^(mon|tue|wed|thu|fri|sat|sun)_[12]_(open|close)$"},"additionalProperties":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}}}},"example":{"website":"https://zernio.com","hours":{"mon_1_open":"09:00","mon_1_close":"18:00"}}}}},"responses":{"200":{"description":"The Page's public info after the update","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacebookPageInfo"}}}},"400":{"x-summary":"The request is invalid, the account is on another platform, or Meta refused the value: send valid fields for a supported account.","description":"Invalid accountId, an empty body, an unknown or malformed field, an account on another platform (`platform_not_supported`), or Meta refused the value (`platform_api_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The API key is not scoped to this account, or Meta refused the edit: use a permitted key or an editing account.","description":"The API key is not scoped to this account, or Meta refused the edit (`platform_api_error`, for example a Page role that cannot edit the Page).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The account is not reachable by the caller (`account_not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"x-summary":"The connection has no Facebook Page selected: select a Page or reconnect the account.","description":"The connection has no Facebook Page selected (`linked_account_required`). Select a Page or reconnect the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/accounts/{accountId}/linkedin-organizations":{"get":{"x-resource-group":"accounts","operationId":"getLinkedInOrganizations","tags":["Connect"],"summary":"List LinkedIn orgs","description":"Returns LinkedIn organizations (company pages) the connected account has admin access to.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Organizations list","content":{"application/json":{"schema":{"type":"object","properties":{"organizations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"vanityName":{"type":"string"},"localizedName":{"type":"string"}}}}}},"example":{"organizations":[{"id":"12345678","name":"Acme Corporation","vanityName":"acme-corp","localizedName":"Acme Corporation"},{"id":"87654321","name":"Acme Subsidiary","vanityName":"acme-sub","localizedName":"Acme Subsidiary"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"}}}},"/v1/accounts/{accountId}/linkedin-aggregate-analytics":{"get":{"x-resource-group":"analytics","operationId":"getLinkedInAggregateAnalytics","tags":["Analytics"],"summary":"Get LinkedIn aggregate stats","description":"Returns aggregate analytics across all posts for a LinkedIn personal account. Requires r_member_postAnalytics scope.\n\nCovers every post authored by the member, whether or not it was published through Zernio (LinkedIn aggregates by member, not by post). Org accounts should use /v1/analytics instead.\n\nSaves (POST_SAVE) and sends (POST_SEND) are available for personal accounts. Organization pages always return 0 for these two metrics because LinkedIn does not expose them on the organization analytics endpoint.\n","parameters":[{"name":"accountId","in":"path","required":true,"description":"The ID of the LinkedIn personal account","schema":{"type":"string"}},{"name":"aggregation","in":"query","required":false,"description":"TOTAL (default, lifetime totals) or DAILY (time series). MEMBERS_REACHED not available with DAILY.","schema":{"type":"string","enum":["TOTAL","DAILY"],"default":"TOTAL"}},{"name":"fromDate","in":"query","required":false,"description":"Start date (YYYY-MM-DD). If omitted, returns lifetime analytics.","schema":{"type":"string","format":"date"},"example":"2024-01-01"},{"name":"toDate","in":"query","required":false,"description":"End date (YYYY-MM-DD, exclusive). Defaults to today if omitted.","schema":{"type":"string","format":"date"},"example":"2024-01-31"},{"name":"startDate","in":"query","required":false,"deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of fromDate, kept for existing callers"},{"name":"endDate","in":"query","required":false,"deprecated":true,"schema":{"type":"string","format":"date"},"description":"Alias of toDate, kept for existing callers"},{"name":"metrics","in":"query","required":false,"description":"Comma-separated metrics: IMPRESSION, MEMBERS_REACHED, REACTION, COMMENT, RESHARE, POST_SAVE, POST_SEND. Omit for all.","schema":{"type":"string"},"example":"IMPRESSION,REACTION,COMMENT,POST_SAVE,POST_SEND"}],"responses":{"200":{"description":"Aggregate analytics data","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/LinkedInAggregateAnalyticsTotalResponse"},{"$ref":"#/components/schemas/LinkedInAggregateAnalyticsDailyResponse"}]},"examples":{"totalAggregation":{"summary":"TOTAL aggregation (lifetime totals)","value":{"accountId":"64abc123def456","platform":"linkedin","accountType":"personal","username":"John Doe","aggregation":"TOTAL","dateRange":null,"analytics":{"impressions":1250000,"reach":450000,"reactions":7500,"comments":2500,"shares":1200,"saves":3400,"sends":900,"engagementRate":1.24},"note":"Aggregate analytics across all posts on this LinkedIn personal account (lifetime totals).","lastUpdated":"2025-01-15T10:30:00.000Z"}},"totalWithDateRange":{"summary":"TOTAL aggregation with date range","value":{"accountId":"64abc123def456","platform":"linkedin","accountType":"personal","username":"John Doe","aggregation":"TOTAL","dateRange":{"startDate":"2024-01-01","endDate":"2024-01-31"},"analytics":{"impressions":125000,"reach":45000,"reactions":750,"comments":250,"shares":120,"saves":340,"sends":90,"engagementRate":1.24},"note":"Aggregate analytics for the specified date range.","lastUpdated":"2025-01-15T10:30:00.000Z"}},"dailyAggregation":{"summary":"DAILY aggregation (time series)","value":{"accountId":"64abc123def456","platform":"linkedin","accountType":"personal","username":"John Doe","aggregation":"DAILY","dateRange":{"startDate":"2024-05-04","endDate":"2024-05-06"},"analytics":{"impressions":[{"date":"2024-05-04","count":1500},{"date":"2024-05-05","count":2300}],"reactions":[{"date":"2024-05-04","count":10},{"date":"2024-05-05","count":20}],"comments":[{"date":"2024-05-04","count":3},{"date":"2024-05-05","count":5}],"shares":[{"date":"2024-05-04","count":2},{"date":"2024-05-05","count":4}],"saves":[{"date":"2024-05-04","count":8},{"date":"2024-05-05","count":12}],"sends":[{"date":"2024-05-04","count":1},{"date":"2024-05-05","count":3}]},"skippedMetrics":["MEMBERS_REACHED (not supported with DAILY aggregation)"],"note":"Daily breakdown of analytics across all posts. MEMBERS_REACHED is not available with DAILY aggregation per LinkedIn API limitations.","lastUpdated":"2025-01-15T10:30:00.000Z"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"param":{"type":"string","description":"The query parameter at fault on a validation failure"},"type":{"type":"string"}}},"examples":{"not_linkedin":{"summary":"Not a LinkedIn account","value":{"error":"This endpoint only supports LinkedIn accounts","code":"invalid_platform"}},"organization":{"summary":"Org account not supported","value":{"error":"Aggregate analytics only available for LinkedIn personal accounts. Organization accounts can use per-post analytics via /v1/analytics.","code":"organization_not_supported"}},"invalid_parameter":{"summary":"Invalid aggregation, metrics or date window (standard error envelope)","value":{"error":"fromDate must be on or before toDate","code":"invalid_field_value","param":"fromDate","type":"invalid_request_error"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"403":{"description":"Missing required LinkedIn scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","example":"missing_scope"},"requiredScope":{"type":"string","example":"r_member_postAnalytics"},"action":{"type":"string","example":"reconnect"}}},"example":{"error":"Missing r_member_postAnalytics scope. Please reconnect your LinkedIn account to grant analytics permissions.","code":"missing_scope","requiredScope":"r_member_postAnalytics","action":"reconnect"}}}},"404":{"description":"Account not found"}}}},"/v1/accounts/{accountId}/linkedin-post-analytics":{"get":{"x-resource-group":"analytics","operationId":"getLinkedInPostAnalytics","tags":["Analytics"],"summary":"Get LinkedIn post stats","description":"Returns analytics for a specific LinkedIn post by URN. Works for both personal and organization accounts. Saves and sends are only populated for personal accounts (LinkedIn does not expose these metrics on the organization analytics endpoint).","parameters":[{"name":"accountId","in":"path","required":true,"description":"The ID of the LinkedIn account","schema":{"type":"string"}},{"name":"urn","in":"query","required":true,"description":"The LinkedIn post URN","schema":{"type":"string"},"example":"urn:li:share:7123456789012345678"}],"responses":{"200":{"description":"Post analytics data","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string","example":"linkedin"},"accountType":{"type":"string","enum":["personal","organization"]},"username":{"type":"string"},"postUrn":{"type":"string"},"analytics":{"type":"object","properties":{"impressions":{"type":"integer","description":"Times the post was shown"},"reach":{"type":"integer","description":"Unique members who saw the post"},"likes":{"type":"integer","description":"Reactions on the post"},"comments":{"type":"integer","description":"Comments on the post"},"shares":{"type":"integer","description":"Reshares of the post"},"saves":{"type":"integer","description":"Times the post was saved (personal accounts only; 0 for organization accounts)"},"sends":{"type":"integer","description":"Times the post was sent via LinkedIn messaging (personal accounts only; 0 for organization accounts)"},"clicks":{"type":"integer","description":"Clicks on the post (organization accounts only)"},"views":{"type":"integer","description":"Video views (video posts only)"},"engagementRate":{"type":"number","description":"Engagement rate, as a percentage rounded to 2 decimals: (likes + comments + shares + clicks + saves + sends) / impressions * 100.\n\nUnlike PostAnalytics.engagementRate on GET /v1/analytics, this one DOES count clicks and has no fallback denominator, so it is 0 whenever impressions is 0.\n\nFor organization accounts the value is the rate LinkedIn returns, not one computed here."}}},"lastUpdated":{"type":"string","format":"date-time"}}},"example":{"accountId":"64abc123def456","platform":"linkedin","accountType":"personal","username":"John Doe","postUrn":"urn:li:share:7123456789012345678","analytics":{"impressions":5420,"reach":3200,"likes":156,"comments":23,"shares":12,"saves":48,"sends":9,"clicks":0,"views":1250,"engagementRate":6.22},"lastUpdated":"2025-01-15T10:30:00.000Z"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["missing_urn","invalid_urn","invalid_platform"]}}},"examples":{"missing_urn":{"value":{"error":"Missing required parameter: urn","code":"missing_urn","example":"urn:li:share:7123456789012345678 or urn:li:ugcPost:7123456789012345678"}},"invalid_urn":{"value":{"error":"Invalid URN format. Must be urn:li:share:ID or urn:li:ugcPost:ID","code":"invalid_urn","providedUrn":"invalid-urn"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans."},"403":{"description":"Missing required LinkedIn scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","example":"missing_scope"},"requiredScope":{"type":"string"},"action":{"type":"string","example":"reconnect"}}}}}},"404":{"description":"Account or post not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}},"examples":{"account_not_found":{"value":{"error":"Account not found"}},"post_not_found":{"value":{"error":"Post not found. The URN may be invalid or the post may have been deleted.","code":"post_not_found","postUrn":"urn:li:share:123"}}}}}},"502":{"$ref":"#/components/responses/UpstreamFailure"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/v1/accounts/{accountId}/linkedin-post-reactions":{"get":{"x-resource-group":"analytics","operationId":"getLinkedInPostReactions","tags":["Analytics"],"summary":"Get LinkedIn post reactions","description":"Returns individual reactions for a specific LinkedIn post, including reactor profiles\n(name, headline/job title, profile picture, profile URL, reaction type).\nOnly works for organization/company page accounts. LinkedIn restricts reaction\ndata for personal profiles (r_member_social_feed is a closed permission).\n","parameters":[{"name":"accountId","in":"path","required":true,"description":"The ID of the LinkedIn organization account","schema":{"type":"string"}},{"name":"urn","in":"query","required":true,"description":"The LinkedIn post URN","schema":{"type":"string","pattern":"^urn:li:(share|ugcPost|activity):[0-9]+$"},"example":"urn:li:share:7123456789012345678"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum number of reactions to return per page"},{"name":"cursor","in":"query","schema":{"type":"integer","minimum":0,"default":0},"description":"Offset-based pagination start index"}],"responses":{"200":{"description":"Reactions with reactor profiles","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string","example":"linkedin"},"accountType":{"type":"string","example":"organization"},"username":{"type":"string"},"postUrn":{"type":"string"},"reactions":{"type":"array","items":{"type":"object","properties":{"reactionType":{"type":"string","description":"LinkedIn reaction enum (LIKE, PRAISE, EMPATHY, INTEREST, APPRECIATION, ENTERTAINMENT)"},"reactionLabel":{"type":"string","description":"User-friendly label (Like, Celebrate, Love, Insightful, Support, Funny)"},"reactedAt":{"type":"string","format":"date-time"},"from":{"type":"object","properties":{"urn":{"type":"string","description":"LinkedIn person or organization URN"},"name":{"type":"string","description":"Reactor's display name"},"headline":{"type":"string","description":"Reactor's headline/job title"},"username":{"type":"string","description":"LinkedIn vanity name"},"profilePicture":{"type":"string","description":"Profile picture URL"},"profileUrl":{"type":"string","description":"Direct link to LinkedIn profile"}}}}}},"pagination":{"type":"object","properties":{"hasMore":{"type":"boolean"},"cursor":{"type":"string","description":"Offset for next page"},"total":{"type":"integer","description":"Total number of reactions (when available)"}}},"lastUpdated":{"type":"string","format":"date-time"}}},"example":{"accountId":"64abc123def456","platform":"linkedin","accountType":"organization","username":"Acme Corp","postUrn":"urn:li:share:7123456789012345678","reactions":[{"reactionType":"LIKE","reactionLabel":"Like","reactedAt":"2026-03-08T12:00:00.000Z","from":{"urn":"urn:li:person:abc123","name":"Jane Smith","headline":"Product Manager at Acme Corp","username":"janesmith","profilePicture":"https://media.licdn.com/...","profileUrl":"https://www.linkedin.com/in/janesmith"}}],"pagination":{"hasMore":true,"cursor":"25","total":156},"lastUpdated":"2026-03-08T12:00:00.000Z"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Analytics access is required: add the Analytics add-on on a legacy plan, or use a usage-based plan where it is included.","description":"Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans."},"403":{"description":"Missing required LinkedIn scope"},"404":{"description":"Account or post not found"}}}},"/v1/accounts/{accountId}/linkedin-organization":{"put":{"x-resource-group":"accounts","operationId":"updateLinkedInOrganization","tags":["Connect"],"summary":"Switch LinkedIn account type","description":"Switch a LinkedIn account between personal profile and organization (company page) posting.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountType"],"properties":{"accountType":{"type":"string","enum":["personal","organization"]},"selectedOrganization":{"type":"object"}}},"example":{"accountType":"organization","selectedOrganization":{"id":"12345678","urn":"urn:li:organization:12345678","name":"Acme Corporation","vanityName":"acme-corp"}}}}},"responses":{"200":{"description":"Account updated","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"accountType":{"type":"string","enum":["personal","organization"]},"accountName":{"type":"string"}}},"example":{"message":"LinkedIn account updated successfully","accountType":"organization","accountName":"Acme Corporation"}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"},"409":{"description":"Another account on this profile is already connected to that destination (profile_platform_conflict).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/accounts/{accountId}/linkedin-mentions":{"get":{"x-resource-group":"accounts","operationId":"getLinkedInMentions","tags":["LinkedIn Mentions"],"summary":"Resolve LinkedIn mention","description":"Converts a LinkedIn profile or company URL to a URN for @mentions in posts.\n\nYou usually do not need this endpoint. Put the profile or company URL inside `@[...]` in the post `content` (for example `@[https://www.linkedin.com/in/vincentjong]`) and the post resolves it for you, using LinkedIn's own name.\n\nUse this endpoint to preview what a URL resolves to, or to get ready-made `@[Name](urn)` markup, which still works in `content` and is published exactly as written.\n\n### Example\n\n1. Resolve: GET /v1/accounts/{id}/linkedin-mentions?url=linkedin.com/in/vincentjong\n2. Returns: mentionFormat: \"@[Vincent Jong](urn:li:person:xxx)\"\n3. Use in post content: \"Great talk with @[Vincent Jong](urn:li:person:xxx) today!\"\n\nImportant: the mentions array field in POST /v1/posts is stored for reference only and does NOT trigger @mentions on LinkedIn. Write the mention in the content text.\n\n### Requirements\n\n- Resolving a profile URL to a person mention requires the LinkedIn account to be admin of at least one organization: both endpoints that resolve a profile URL to a member URN take an organization you administer.\n- A resolved person mention publishes from any account. Organization mentions (e.g. @Microsoft) have no such requirement.\n- Person mentions DO work when published from personal profiles (the URN only needs to be valid). The limitation is only in the resolution step (URL to URN), not in publishing.\n\n### Why a profile can 404\n\nThe two resolution endpoints are not scoped alike:\n\n- peopleTypeahead?q=organizationFollowers only returns that organization's followers.\n- vanityUrl?q=vanityUrlAsOrganization does not, and its resolvable set is opaque.\n\nA 404 here does not mean the person is unknown to you or unknown to LinkedIn: a live public profile can 404 with no reason given.\n\n### Display name\n\ndisplayName is deprecated and ignored in practice: the endpoint reads the person's real name from LinkedIn itself. LinkedIn renders a person mention as a link only when the mention text is the person's first name, last name or full name (case-sensitive).\n","parameters":[{"name":"accountId","in":"path","required":true,"description":"The LinkedIn account ID","schema":{"type":"string"}},{"name":"url","in":"query","required":true,"description":"LinkedIn profile URL, company URL, or vanity name.","schema":{"type":"string"},"examples":{"personVanityName":{"value":"miquelpalet","summary":"Person, only the vanity name"},"personFullUrl":{"value":"https://www.linkedin.com/in/miquelpalet","summary":"Person - full LinkedIn URL"},"orgShortUrl":{"value":"company/microsoft","summary":"Org - short format"},"orgFullUrl":{"value":"https://www.linkedin.com/company/microsoft","summary":"Org - full LinkedIn URL"}}},{"name":"displayName","in":"query","required":false,"deprecated":true,"description":"Deprecated: omit it. When omitted, the real name is read from LinkedIn. Ignored for org mentions, which always use the organization's LinkedIn name.\n\nWhen sent for a person, it overrides the mention text, and LinkedIn renders the mention only if it is exactly the person's first name, last name or full name (case-sensitive).\n","schema":{"type":"string"},"examples":{"personName":{"value":"Miquel Palet","summary":"Exact name as shown on LinkedIn profile"},"orgName":{"value":"Microsoft","summary":"Company name (optional for orgs)"}}}],"responses":{"200":{"description":"URN resolved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"urn":{"type":"string","description":"The LinkedIn URN (person or organization)","example":"urn:li:person:4qj5ox-agD"},"type":{"type":"string","enum":["person","organization"],"description":"The type of entity (person or organization)","example":"person"},"displayName":{"type":"string","description":"Display name (provided, from API, or derived from vanity URL)","example":"Miquel Palet"},"mentionFormat":{"type":"string","description":"Ready-to-use mention format for post content","example":"@[Miquel Palet](urn:li:person:4qj5ox-agD)"},"vanityName":{"type":"string","description":"The vanity name/slug (only for organization mentions)","example":"microsoft"},"warning":{"type":"string","description":"Only present for person mentions when displayName was not provided and the real name could not be resolved from LinkedIn","example":"Could not resolve real name from LinkedIn. Display name was derived from the vanity URL and may not match the profile exactly."}}},"examples":{"personWithDisplayName":{"summary":"Person mention with a displayName override (must match the person's first name, last name or full name exactly, or the mention is not a link)","value":{"urn":"urn:li:person:4qj5ox-agD","type":"person","displayName":"Miquel Palet","mentionFormat":"@[Miquel Palet](urn:li:person:4qj5ox-agD)"}},"personWithoutDisplayName":{"summary":"Person mention whose real name could not be resolved (name derived from the vanity URL)","value":{"urn":"urn:li:person:4qj5ox-agD","type":"person","displayName":"Miquelpalet","mentionFormat":"@[Miquelpalet](urn:li:person:4qj5ox-agD)","warning":"Could not resolve real name from LinkedIn. Display name was derived from the vanity URL and may not match the profile exactly."}},"organization":{"summary":"Org mention","value":{"urn":"urn:li:organization:1035","type":"organization","displayName":"Microsoft","mentionFormat":"@[Microsoft](urn:li:organization:1035)","vanityName":"microsoft"}}}}}},"400":{"description":"Invalid request or no organization found (for person mentions)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missingUrl":{"value":{"error":"url parameter is required","type":"invalid_request_error","code":"missing_required_field","param":"url"}},"noOrgForPersonMention":{"value":{"error":"No organization found. You need to be an admin of a LinkedIn organization to use person mentions. Organization mentions work without this requirement.","type":"invalid_request_error","code":"linkedin_mention_no_organization"}}}}}},"401":{"x-summary":"The API key is missing or invalid, or LinkedIn revoked the account token: send a valid key or reconnect the account.","description":"Missing or invalid API key (`missing_credentials` or `invalid_credentials`), or LinkedIn revoked or expired the account's token (`reconnect_required`, reconnect the account).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missingCredentials":{"value":{"error":"Missing API key. Send it as Authorization: Bearer <your API key>.","type":"authentication_error","code":"missing_credentials","docUrl":"https://docs.zernio.com"}},"reconnectRequired":{"value":{"error":"Token expired or revoked for LinkedIn. Please reconnect your account.","type":"permission_error","code":"reconnect_required","platform":"linkedin"}}}}}},"403":{"description":"The account holds no organization role that can resolve person mentions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"noPostingRole":{"value":{"error":"LinkedIn blocked this lookup. Your account has no company page where it can create posts, which LinkedIn requires to resolve a person's profile URL. Ask for an Admin or Content Admin role on one of your pages, or mention a company instead.","type":"permission_error","code":"linkedin_mention_lookup_forbidden"}}}}}},"404":{"description":"Account, person or organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"memberNotFound":{"value":{"error":"LinkedIn couldn't resolve this profile. Not every profile is resolvable through LinkedIn's API, even public ones, and LinkedIn gives no reason. Check the profile address is current (people can change theirs), or mention a company instead.","type":"not_found","code":"linkedin_person_not_resolvable"}},"orgNotFound":{"value":{"error":"Organization not found. Check the LinkedIn company URL is correct.","type":"not_found","code":"linkedin_organization_not_found"}},"accountNotFound":{"value":{"error":"LinkedIn account not found","type":"not_found","code":"account_not_found"}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/accounts/{accountId}/instagram/stories":{"get":{"x-resource-group":"analytics","operationId":"listInstagramStories","tags":["Instagram"],"summary":"List active Instagram stories","description":"Returns the IG Business/Creator account's currently-active stories.\nMeta keeps stories live for 24h; expired stories are not returned.\n\nLimitations propagated from Meta (these are NOT bugs):\n- 24h window only\n- Live videos excluded\n- Reshared stories not returned\n- `mediaUrl` may be null if Meta flagged the story for copyright\n- `caption`, `likeCount`, `commentsCount` do not apply to story media\n","parameters":[{"name":"accountId","in":"path","required":true,"description":"The Instagram account ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Active stories","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"Instagram media ID of the story."},"mediaType":{"type":["string","null"],"description":"IMAGE / VIDEO / CAROUSEL_ALBUM"},"mediaProductType":{"type":["string","null"],"description":"Always 'STORY' for this endpoint."},"mediaUrl":{"type":["string","null"],"description":"Direct media URL. Null if Meta flagged the story for copyright. URL expires when the story expires."},"permalink":{"type":["string","null"],"description":"Public Instagram permalink to the story (only viewable while live)."},"thumbnailUrl":{"type":["string","null"],"description":"Thumbnail URL for video stories."},"timestamp":{"type":["string","null"],"format":"date-time","description":"When the story was posted."}}}}}}}}},"400":{"description":"Invalid request."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/accounts/{accountId}/instagram/publishing-limit":{"get":{"x-resource-group":"accounts","operationId":"getInstagramPublishingLimit","tags":["Instagram"],"summary":"Get Instagram publishing limit","description":"Returns the account's remaining content-publishing quota for Instagram's rolling\n24-hour window, so you can pace publishing and warn before the cap is reached.\n\n`quotaUsage` counts containers published since the start of the window.\nAlways compare against the returned `quotaTotal` rather than hardcoding a number:\nMeta's prose documentation and the live API disagree on the value, and the live\nvalue is authoritative.\n","parameters":[{"name":"accountId","in":"path","required":true,"description":"The ID of the Instagram account","schema":{"type":"string"}}],"responses":{"200":{"description":"Remaining publishing quota for the rolling window","content":{"application/json":{"schema":{"type":"object","properties":{"quotaUsage":{"type":"integer","description":"Containers published so far in the current window"},"quotaTotal":{"type":"integer","description":"Maximum containers publishable per window"},"quotaDurationSeconds":{"type":"integer","description":"Length of the rolling window in seconds"}}},"example":{"quotaUsage":3,"quotaTotal":50,"quotaDurationSeconds":86400}}}},"400":{"description":"Not an Instagram account"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"502":{"description":"Instagram rejected the request"}}}},"/v1/accounts/{accountId}/instagram/audio":{"get":{"x-resource-group":"accounts","operationId":"searchInstagramAudio","tags":["Instagram"],"summary":"Search Instagram audio","description":"Search Instagram's audio catalog (licensed music or original sounds),\nor list what is currently trending by omitting `q`. Returns up to ~30\nassets; Meta exposes no pagination on this edge.\n\nPass the returned `audioId` as\n`platformSpecificData.audioConfiguration.audioId` when creating a Reel\nto publish it with that track.\n\nRequires an Instagram account connected via **Facebook Login**. Meta\nhosts this catalog on graph.facebook.com only, so accounts connected\nwith classic Instagram Login receive a 400\n(`instagram_audio_requires_facebook_login`) and must be reconnected\nchoosing the Facebook option.\n","parameters":[{"name":"accountId","in":"path","required":true,"description":"The ID of the Instagram account","schema":{"type":"string"}},{"name":"audioType","in":"query","required":true,"description":"Catalog to search: licensed music or original sounds from Reels.","schema":{"type":"string","enum":["music","original_sound"]}},{"name":"q","in":"query","required":false,"description":"Search keywords. Omit to get the current trending list.","schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"Matching audio assets (may be empty)","content":{"application/json":{"schema":{"type":"object","properties":{"audio":{"type":"array","items":{"$ref":"#/components/schemas/InstagramAudioAsset"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"502":{"description":"Instagram rejected the request"}}}},"/v1/accounts/{accountId}/instagram/audio/{audioId}":{"get":{"x-resource-group":"accounts","operationId":"getInstagramAudio","tags":["Instagram"],"summary":"Get Instagram audio metadata","description":"Fetch one audio asset's metadata by ID. Use it to re-validate a stored\n`audioId` before a scheduled Reel publishes, or to refresh the preview\n`downloadUrl` (Meta expires preview URLs after roughly 1.5 days).\n\nSame connection requirement as the search endpoint: Facebook-Login\nInstagram accounts only.\n","parameters":[{"name":"accountId","in":"path","required":true,"description":"The ID of the Instagram account","schema":{"type":"string"}},{"name":"audioId","in":"path","required":true,"description":"Instagram audio asset ID","schema":{"type":"string","pattern":"^\\d{1,30}$"}}],"responses":{"200":{"description":"The audio asset","content":{"application/json":{"schema":{"type":"object","properties":{"audio":{"$ref":"#/components/schemas/InstagramAudioAsset"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"502":{"description":"Instagram rejected the request"}}}},"/v1/accounts/{accountId}/instagram/business-discovery":{"get":{"x-resource-group":"analytics","operationId":"getInstagramBusinessDiscovery","tags":["Instagram"],"summary":"Look up a public Instagram Business account","description":"Returns the public profile and most recent media of any Instagram\nBusiness or Creator account, looked up by username through one of your\nconnected Instagram accounts. Useful for competitor and market research.\nPersonal accounts and private accounts cannot be looked up.\n\nRequires an Instagram account connected via **Facebook Login**. Meta\nserves business discovery on graph.facebook.com only, so accounts\nconnected with classic Instagram Login receive a 400\n(`instagram_business_discovery_requires_facebook_login`) and must be\nreconnected choosing the Facebook option. Any one such account can look\nup any public Business or Creator handle.\n\n`likeCount` is null when the owner hides like counts.\n\nMedia URLs are temporary, and fields Meta does not return come back as null, never omitted.\n","parameters":[{"name":"accountId","in":"path","required":true,"description":"The ID of a connected Instagram account (Facebook Login).","schema":{"type":"string"}},{"name":"username","in":"query","required":true,"description":"Instagram handle to look up, with or without the leading @. Case-insensitive.","schema":{"type":"string","maxLength":31,"example":"nike"}},{"name":"limit","in":"query","required":false,"description":"How many of the most recent media to return.","schema":{"type":"integer","minimum":1,"maximum":25,"default":12}}],"responses":{"200":{"description":"Public profile and recent media","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstagramBusinessDiscovery"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"x-summary":"The account is not reachable by the caller, or no public Business or Creator account has that username: check both values.","description":"The account is not reachable by the caller (`account_not_found`), or no public Business or Creator account has that username (`instagram_profile_not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/accounts/{accountId}/instagram/media/{mediaId}/collaborators":{"get":{"x-resource-group":"publishing","operationId":"listInstagramMediaCollaborators","tags":["Instagram"],"summary":"List the collaborators of an Instagram post","description":"Returns the accounts invited as collaborators on one of the connected\naccount's own posts (feed image, Reel or carousel), with whether each\ninvitation was accepted or is still pending. Use it to check who\naccepted a collab post after publishing it.\n\nRequires an Instagram account connected via **Facebook Login**. Meta\nserves this edge on graph.facebook.com only, so accounts connected with\nclassic Instagram Login receive a 400\n(`instagram_collaborators_require_facebook_login`) and must be\nreconnected choosing the Facebook option.\n\nMeta returns at most 5 collaborators and only those who allow\ncollaborator tagging. A post without collaborators returns an empty list.\n","parameters":[{"name":"accountId","in":"path","required":true,"description":"The ID of a connected Instagram account (Facebook Login).","schema":{"type":"string"}},{"name":"mediaId","in":"path","required":true,"description":"Instagram media ID of a post published by this account (digits only, e.g. the platformPostId of a published post).","schema":{"type":"string","pattern":"^[0-9]+$","example":"18063237463112345"}}],"responses":{"200":{"description":"Collaborators of the post","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/InstagramMediaCollaborator"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"x-summary":"The account is not reachable by the caller, or the media does not exist for this account: check both IDs.","description":"The account is not reachable by the caller (`account_not_found`), or the media does not exist or does not belong to this account (`resource_not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/accounts/{accountId}/instagram/live-media":{"get":{"x-resource-group":"analytics","operationId":"listInstagramLiveMedia","tags":["Instagram"],"summary":"List the live broadcasts of an Instagram account","description":"Returns the live videos the connected Instagram account is broadcasting right now.\n\nMeta only returns broadcasts in progress at the time of the request, so the list is empty when nothing is live (a 200, not an error).\n\nPair the returned `id` with comments flagged as live (the live_comments webhook field) or with a `live_comment` comment automation.\n\n### Requires Facebook Login\n\nThe Instagram account must be connected via **Facebook Login**. Meta documents the live_media edge on graph.facebook.com only.\n\nAccounts connected with classic Instagram Login receive a 400 (`instagram_live_media_requires_facebook_login`) and must be reconnected choosing the Facebook option.\n","parameters":[{"name":"accountId","in":"path","required":true,"description":"The ID of a connected Instagram account (Facebook Login).","schema":{"type":"string"}}],"responses":{"200":{"description":"Live broadcasts in progress","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InstagramLiveMedia"}}}}}}},"400":{"x-summary":"The accountId is invalid, the account is on another platform, or it uses Instagram Login: use an account connected with Facebook Login.","description":"Invalid accountId, an account on another platform (`platform_not_supported`) or an account connected with Instagram Login (`instagram_live_media_requires_facebook_login`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is not scoped to this account, or Meta refused the request (`platform_api_error`, for example a missing permission).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The account is not reachable by the caller (`account_not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/accounts/{accountId}/instagram/tags":{"get":{"x-resource-group":"analytics","operationId":"listInstagramTaggedMedia","tags":["Instagram"],"summary":"List the posts an Instagram account is tagged in","description":"Returns the media where other Instagram users photo-tagged the connected\naccount, newest first. Private media is never returned.\n\nCursor-paginated: pass `nextCursor` from the previous response as\n`cursor` to read the next page. `nextCursor` is null when there are no\nmore pages. Meta does not say whether a page is the last one, so the\nfinal page can come back empty with `nextCursor` null.\n\nRequires an Instagram account connected via **Facebook Login**. Meta\ndoes not give Instagram Login access to tagging, so accounts connected\nwith classic Instagram Login receive a 400\n(`instagram_tagged_media_requires_facebook_login`) and must be\nreconnected choosing the Facebook option.\n","parameters":[{"name":"accountId","in":"path","required":true,"description":"The ID of a connected Instagram account (Facebook Login).","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","minLength":1,"maxLength":1000}}],"responses":{"200":{"description":"One page of tagged media","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InstagramTaggedMedia"}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to read the next page. Null when there are no more pages."}}}}}},"400":{"x-summary":"A parameter is invalid, the account is on another platform, or it uses Instagram Login: fix the request or use Facebook Login.","description":"Invalid accountId, limit or cursor, an account on another platform (`platform_not_supported`) or an account connected with Instagram Login (`instagram_tagged_media_requires_facebook_login`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is not scoped to this account, or Meta refused the request (`platform_api_error`, for example a missing permission).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The account is not reachable by the caller (`account_not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/accounts/{accountId}/instagram/mentions/media/{mediaId}":{"get":{"x-resource-group":"engagement","operationId":"getInstagramMentionedMedia","tags":["Instagram"],"summary":"Get a post that mentions an Instagram account in its caption","description":"Returns a post in which another Instagram user @mentioned the\nconnected account in the caption. Meta sends the media ID in its\nmention notification and offers no list of mentions, so this reads one\nmention by ID. Mentions in Stories are not supported by Meta.\n\nRequires an Instagram account connected via **Facebook Login**. Meta\nserves mentions on graph.facebook.com only, so accounts connected with\nclassic Instagram Login receive a 400\n(`instagram_mentions_require_facebook_login`) and must be reconnected\nchoosing the Facebook option.\n","parameters":[{"name":"accountId","in":"path","required":true,"description":"The ID of a connected Instagram account (Facebook Login).","schema":{"type":"string"}},{"name":"mediaId","in":"path","required":true,"description":"Instagram media ID of the post that mentions the account (digits only).","schema":{"type":"string","pattern":"^[0-9]+$","maxLength":32,"example":"18027939643230671"}}],"responses":{"200":{"description":"Get a post that mentions an Instagram account in its caption","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstagramMentionedMedia"}}}},"400":{"x-summary":"A parameter is invalid, the account is on another platform or uses Instagram Login, or Meta rejected it: fix the request.","description":"Invalid accountId or mediaId, an account on another platform (`platform_not_supported`), an account connected with Instagram Login (`instagram_mentions_require_facebook_login`), or a Meta rejection (`platform_api_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is not scoped to this account, or Meta refused the request (`platform_api_error`, for example a missing permission).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"x-summary":"The account is not reachable by the caller, or the media does not exist or lacks a mention: check both IDs.","description":"The account is not reachable by the caller (`account_not_found`), or the media does not exist or does not mention the account in its caption (`resource_not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/accounts/{accountId}/instagram/mentions/comments/{commentId}":{"get":{"x-resource-group":"engagement","operationId":"getInstagramMentionedComment","tags":["Instagram"],"summary":"Get a comment that mentions an Instagram account","description":"Returns a comment in which another Instagram user @mentioned the connected account, with the post it was left on.\n\nMeta sends the comment ID in its mention notification and offers no list of mentions, so this reads one mention by ID. Meta answers an error when comments are disabled on that post.\n\n### Requires Facebook Login\n\nThe Instagram account must be connected via **Facebook Login**. Meta serves mentions on graph.facebook.com only.\n\nAccounts connected with classic Instagram Login receive a 400 (`instagram_mentions_require_facebook_login`) and must be reconnected choosing the Facebook option.\n","parameters":[{"name":"accountId","in":"path","required":true,"description":"The ID of a connected Instagram account (Facebook Login).","schema":{"type":"string"}},{"name":"commentId","in":"path","required":true,"description":"Instagram comment ID of the comment that mentions the account (digits only).","schema":{"type":"string","pattern":"^[0-9]+$","maxLength":32,"example":"17894227972186120"}}],"responses":{"200":{"description":"Get a comment that mentions an Instagram account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstagramMentionedComment"}}}},"400":{"x-summary":"A parameter is invalid, the account is on another platform or uses Instagram Login, or Meta rejected it: fix the request.","description":"Invalid accountId or commentId, an account on another platform (`platform_not_supported`), an account connected with Instagram Login (`instagram_mentions_require_facebook_login`), or a Meta rejection (`platform_api_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is not scoped to this account, or Meta refused the request (`platform_api_error`, for example a missing permission).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"x-summary":"The account is not reachable by the caller, or the comment does not exist or does not mention it: check both IDs.","description":"The account is not reachable by the caller (`account_not_found`), or the comment does not exist or does not mention the account (`resource_not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/accounts/{accountId}/instagram/stories/{storyId}/insights":{"get":{"x-resource-group":"analytics","operationId":"getInstagramStoryInsights","tags":["Instagram"],"summary":"Get Instagram story insights","description":"Returns metrics for a single story. The `source` field discriminates between three states:\n\n- `live`: fetched from Meta in real time (story is still active)\n- `cached`: fetched from a persisted `story_insights` webhook payload (story has expired but we received its final-state metrics from Meta)\n- `unavailable`: story has expired and Meta sent no `story_insights` webhook for it\n\nMeta sends that webhook most reliably for accounts connected with Facebook Login or with their linked Facebook Page connected. So read insights while the story is live if you need final numbers.\n\nMeta can report an expired story as an empty successful result rather than an error. So an expired story resolves to `cached` or `unavailable` even though the upstream request itself succeeded.\n\n### Field semantics\n\nField semantics follow Meta's API.\n\n- Counts below 5 may be returned as 0 due to Meta's privacy floor on small audiences.\n- The `navigation` field is the sum of `tapsForward + tapsBack + exits + swipesForward`.\n","parameters":[{"name":"accountId","in":"path","required":true,"description":"The Instagram account ID","schema":{"type":"string"}},{"name":"storyId","in":"path","required":true,"description":"The Instagram media ID of the story.","schema":{"type":"string"}}],"responses":{"200":{"description":"Story insights","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["source","metrics"],"properties":{"source":{"type":"string","enum":["live","cached","unavailable"]},"metrics":{"type":"object","required":["views","reach","replies","shares","navigation","tapsForward","tapsBack","exits","swipesForward","profileVisits","follows","reposts","totalInteractions"],"properties":{"views":{"type":"integer","description":"Total story plays. Replaces deprecated 'impressions' for media created after 2024-07-02."},"reach":{"type":"integer","description":"Unique accounts that saw the story."},"replies":{"type":"integer","description":"DMs sent in reply to the story."},"shares":{"type":"integer"},"navigation":{"type":"integer","description":"Total nav actions (tapsForward + tapsBack + exits + swipesForward)."},"tapsForward":{"type":"integer","description":"Tapped right to next slide of SAME story."},"tapsBack":{"type":"integer","description":"Tapped left to previous slide."},"exits":{"type":"integer","description":"Closed Stories interface entirely."},"swipesForward":{"type":"integer","description":"Swiped left to next account's story."},"profileVisits":{"type":"integer"},"follows":{"type":"integer"},"reposts":{"type":"integer"},"totalInteractions":{"type":"integer"}}}}}}}}}},"400":{"description":"Invalid request."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"502":{"description":"Instagram rejected the request."}}}},"/v1/accounts/{accountId}/pinterest-boards":{"get":{"x-resource-group":"accounts","operationId":"getPinterestBoards","tags":["Connect"],"summary":"List Pinterest boards","description":"Returns the boards available for a connected Pinterest account. Use this to get a board ID when creating a Pinterest post.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Boards list","content":{"application/json":{"schema":{"type":"object","properties":{"boards":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"privacy":{"type":"string"}}}}}},"example":{"boards":[{"id":"123456789012345678","name":"Marketing Ideas","description":"Collection of marketing inspiration","privacy":"PUBLIC"},{"id":"234567890123456789","name":"Product Photos","description":"Product photography","privacy":"PUBLIC"}]}}}},"400":{"description":"Not a Pinterest account"},"401":{"x-summary":"The API key is missing or invalid, or the Pinterest token was revoked or expired: send a valid key or reconnect.","description":"Missing or invalid API key (missing_credentials / invalid_credentials), or the stored Pinterest token was revoked or expired (reconnect_required): reconnect the account."},"404":{"description":"Account not found"},"409":{"x-summary":"The account has no stored access token: reconnect it.","description":"The account has no stored access token (ads_connection_required). Reconnect it."},"502":{"description":"Pinterest rejected or failed the request."}}},"put":{"x-resource-group":"accounts","operationId":"updatePinterestBoards","tags":["Connect"],"summary":"Set default Pinterest board","description":"Sets the default board used when publishing pins for this account.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["defaultBoardId"],"properties":{"defaultBoardId":{"type":"string"},"defaultBoardName":{"type":"string"}}},"example":{"defaultBoardId":"123456789012345678","defaultBoardName":"Marketing Ideas"}}}},"responses":{"200":{"description":"Default board set","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"account":{"$ref":"#/components/schemas/SocialAccount"}}},"example":{"message":"Default Pinterest board updated successfully","account":{"_id":"64e1f0a9e2b5af0012ab34cd","platform":"pinterest","username":"mybrand","displayName":"My Brand","isActive":true}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"}}},"post":{"x-resource-group":"accounts","operationId":"createPinterestBoard","tags":["Connect"],"summary":"Create Pinterest board","description":"Creates a new board on the connected Pinterest account. The returned board ID can be used immediately as `platformSpecificData.boardId` when creating a Pinterest post.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Name of the board"},"description":{"type":"string","description":"Board description"},"privacy":{"type":"string","enum":["PUBLIC","PROTECTED","SECRET"],"default":"PUBLIC","description":"Board privacy setting"}}},"example":{"name":"Summer Recipes","description":"My favorite summer recipes","privacy":"PUBLIC"}}}},"responses":{"201":{"description":"Board created","content":{"application/json":{"schema":{"type":"object","properties":{"board":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"privacy":{"type":"string"},"url":{"type":"string"}}}}},"example":{"board":{"id":"345678901234567890","name":"Summer Recipes","description":"My favorite summer recipes","privacy":"PUBLIC"}}}}},"400":{"description":"Invalid request or not a Pinterest account"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"},"502":{"description":"Pinterest rejected the request (e.g. duplicate board name)"}}}},"/v1/accounts/{accountId}/youtube-captions":{"get":{"x-resource-group":"accounts","operationId":"getYoutubeCaptions","tags":["Connect"],"summary":"Get a YouTube video transcript","description":"Returns the caption track YouTube already holds for one of the connected channel's own videos, as plain text plus timed cues. Use it instead of downloading and transcribing the video yourself.\n\nAuto-generated (ASR) tracks are included: YouTube serves them to the channel owner, which is what the connected account is. Uploaded tracks win over auto-generated ones when both exist for a language.\n\n### Caching\n\nWe store the transcript on first read and serve it from there afterwards, so you do not need to cache it yourself. A cached read costs no YouTube quota and does not call YouTube at all.\n\n- `source` tells you which happened: `youtube` on the first read, `cache` after.\n- Pass `refresh=true` only when the captions actually changed on YouTube, since that re-downloads.\n\n### Notes\n\n- Only videos owned by this connected channel. Anything else returns 404.\n- `contentDetails.caption` in YouTube's own API reads `false` on videos that DO have a serving auto-generated track, so it is not a usable availability signal. Call this endpoint and handle the 404.\n- YouTube generates auto-captions only for videos with recognisable speech, and can take a few hours after upload to publish them.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"The connected YouTube account."},{"name":"videoId","in":"query","required":true,"schema":{"type":"string"},"description":"The YouTube video id (the `platformPostId` on a synced external post)."},{"name":"language","in":"query","schema":{"type":"string"},"description":"BCP-47 language tag as YouTube labels the track. `en` also matches an `en-GB` track. Omit to take the best available track."},{"name":"format","in":"query","schema":{"type":"string","enum":["json","srt"],"default":"json"},"description":"`json` returns timed `cues`; `srt` returns the raw SubRip body instead. `text` is present either way."},{"name":"refresh","in":"query","schema":{"type":"boolean","default":false},"description":"Re-download from YouTube instead of serving the stored copy. Spends 200 quota units."}],"responses":{"200":{"description":"The transcript.","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"},"videoId":{"type":"string"},"language":{"type":"string","description":"The language of the returned track."},"trackId":{"type":"string","description":"YouTube's own caption track id."},"trackKind":{"type":"string","enum":["asr","standard"],"description":"`asr` is YouTube's auto-generated track; `standard` was uploaded by the channel."},"source":{"type":"string","enum":["cache","youtube"],"description":"`cache` when served from our stored copy, `youtube` when this call spent the quota units."},"fetchedAt":{"type":"string","format":"date-time","description":"When the stored copy was downloaded from YouTube."},"text":{"type":"string","description":"The whole transcript as one paragraph, no timings."},"cues":{"type":"array","description":"Timed cues. Present when format is json. Auto-generated cues overlap in time by design (captions roll), so `start` can precede the previous cue's `end`.","items":{"type":"object","properties":{"start":{"type":"number","description":"Seconds from the start of the video."},"end":{"type":"number"},"text":{"type":"string"}}}},"srt":{"type":"string","description":"Raw SubRip body. Present when format is srt."},"availableTracks":{"type":"array","description":"Every track on the video, so you can re-request another language. On a cached read this is the listing as it stood when we downloaded, so a language added to the video since then appears only after a `refresh=true` or when you request that language directly.","items":{"type":"object","properties":{"trackId":{"type":"string"},"language":{"type":"string"},"trackKind":{"type":"string","enum":["asr","standard"]},"name":{"type":"string","description":"The track's display name. Empty for auto-generated tracks."}}}}}},"example":{"accountId":"68a1f2c3d4e5f6a7b8c9d0e1","videoId":"sdw1FML60tM","language":"en","trackId":"AUieDaanCEjmJQdL7wfZbe1QDQTbseX-hToYw99pmOJitlJz868","trackKind":"asr","source":"cache","fetchedAt":"2026-08-27T21:09:54.000Z","text":"Hey, this is Mickey. I'm the founder of this portfolio of three websites which are mainly monetized via AdSense.","cues":[{"start":1.6,"end":8.88,"text":"Hey, this is Mickey. I'm the founder of"},{"start":5.04,"end":12.8,"text":"this portfolio of three websites"}],"availableTracks":[{"trackId":"AUieDaanCEjmJQdL7wfZbe1QDQTbseX-hToYw99pmOJitlJz868","language":"en","trackKind":"asr","name":""}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"x-summary":"The account is not found, the video is not on this channel, or it lacks a caption track in that language.","description":"Account not found, the video does not belong to this channel (`video_not_found`), or the video has no caption track in the requested language (`captions_not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"This video has no caption tracks. YouTube generates them only for videos with recognisable speech, and it can take a few hours after upload.","type":"not_found","code":"captions_not_found","param":"videoId"}}}}}}},"/v1/accounts/{accountId}/youtube-playlists":{"get":{"x-resource-group":"accounts","operationId":"getYoutubePlaylists","tags":["Connect"],"summary":"List YouTube playlists","description":"Returns the playlists available for a connected YouTube account. Use this to get a playlist ID when creating a YouTube post with the playlistId field.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Playlists list","content":{"application/json":{"schema":{"type":"object","properties":{"playlists":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"privacy":{"type":"string","enum":["public","private","unlisted"]},"itemCount":{"type":"integer"},"thumbnailUrl":{"type":"string"}}}},"defaultPlaylistId":{"type":["string","null"]}}},"example":{"playlists":[{"id":"PLxxxxxxxxxxxxx","title":"Tutorials","description":"Step-by-step video tutorials","privacy":"public","itemCount":24,"thumbnailUrl":"https://i.ytimg.com/vi/xxx/mqdefault.jpg"},{"id":"PLyyyyyyyyyyyyy","title":"Vlogs","description":"Weekly vlogs","privacy":"public","itemCount":52,"thumbnailUrl":"https://i.ytimg.com/vi/yyy/mqdefault.jpg"}],"defaultPlaylistId":null}}}},"400":{"description":"Not a YouTube account"},"401":{"x-summary":"The API key is missing or invalid, or the YouTube token was revoked or expired: send a valid key or reconnect.","description":"Missing or invalid API key (missing_credentials / invalid_credentials), or the stored YouTube token was revoked or expired (reconnect_required): reconnect the account."},"404":{"description":"Account not found"}}},"post":{"x-resource-group":"accounts","operationId":"createYoutubePlaylist","tags":["Connect"],"summary":"Create YouTube playlist","description":"Creates an empty playlist on the connected YouTube channel. Requires a title; privacy defaults to private.\n\nReturns the same playlist shape as the list endpoint. Pass the returned playlist.id as platformSpecificData.playlistId when publishing a video. Does not change the account's default playlist.\n\n### Requirements and cost\n\n- Requires the youtube or youtube.force-ssl OAuth scope.\n- Costs 50 YouTube quota units.\n\n### Retries\n\nThis operation is not idempotent and is not automatically retried. Repeating a request can create another playlist, including after a timeout. List playlists before retrying an ambiguous failure.\n\n### Official series\n\nOfficial series settings are not exposed by YouTube's public API and must be enabled manually in YouTube's desktop playlist settings.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","minLength":1,"description":"Playlist title. Leading and trailing whitespace is removed."},"description":{"type":"string","description":"Optional playlist description."},"privacy":{"type":"string","enum":["private","public","unlisted"],"default":"private"}}},"example":{"title":"Tutorials","description":"Step-by-step video tutorials","privacy":"private"}}}},"responses":{"201":{"description":"Playlist created","content":{"application/json":{"schema":{"type":"object","required":["playlist"],"properties":{"playlist":{"type":"object","required":["id","title","description","privacy","itemCount","thumbnailUrl"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"privacy":{"type":"string","enum":["private","public","unlisted"]},"itemCount":{"type":"integer"},"thumbnailUrl":{"type":"string"}}}}},"example":{"playlist":{"id":"PLxxxxxxxxxxxxx","title":"Tutorials","description":"Step-by-step video tutorials","privacy":"private","itemCount":0,"thumbnailUrl":""}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"API key lacks access to the account or YouTube denied permission."},"404":{"description":"Account not found or inaccessible."},"429":{"description":"YouTube rate limit exceeded."},"502":{"x-summary":"The YouTube request failed: check existing playlists before retrying, because the playlist may already have been created.","description":"YouTube request failed. Check existing playlists before retrying, because the playlist may have been created."}}},"put":{"x-resource-group":"accounts","operationId":"updateYoutubeDefaultPlaylist","tags":["Connect"],"summary":"Set default YouTube playlist","description":"Sets the default playlist used when publishing videos for this account. When a post does not specify a playlistId, the default playlist is not automatically used (it is stored for client-side convenience).","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["defaultPlaylistId"],"properties":{"defaultPlaylistId":{"type":"string","minLength":1},"defaultPlaylistName":{"type":"string"}}},"example":{"defaultPlaylistId":"PLxxxxxxxxxxxxx","defaultPlaylistName":"Tutorials"}}}},"responses":{"200":{"description":"Default playlist set","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"}}}},"/v1/accounts/{accountId}/gmb-locations":{"get":{"x-resource-group":"accounts","operationId":"getGmbLocations","tags":["Connect"],"summary":"List Google Business Profile locations","description":"Returns Google Business Profile locations the connected account can access, plus the currently selected location.\n\nThe list is bounded (see hasMore). For accounts that own many locations:\n\n- use the search or filter query params to find a specific one instead of loading them all;\n- or raise limit to enumerate an account with more than 100 locations.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Free-text search on the business name, applied server-side by Google. Use for accounts with many locations."},{"name":"filter","in":"query","required":false,"schema":{"type":"string"},"description":"Raw Google Business Information API filter expression (advanced; takes precedence over search), e.g. storeCode=\"LH279411\"."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"description":"Max locations to return (default 100, max 500). Raise it to enumerate an account with more than 100 locations; for accounts with thousands, use search/filter instead."}],"responses":{"200":{"description":"Locations list","content":{"application/json":{"schema":{"type":"object","properties":{"locations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"accountId":{"type":"string"},"accountName":{"type":"string"},"address":{"type":"string"},"category":{"type":"string"},"websiteUrl":{"type":"string"},"storeCode":{"type":"string"}}}},"hasMore":{"type":"boolean","description":"True when more locations exist than were returned (use search to narrow down)."},"selectedLocationId":{"type":"string"},"cached":{"type":"boolean"}}},"example":{"locations":[{"id":"12345678901234567890","name":"My Business Location","accountId":"accounts/123456789","accountName":"My Business Account","address":"123 Main St, San Francisco, CA","category":"Restaurant","websiteUrl":"https://mybusiness.com"}],"selectedLocationId":"12345678901234567890","cached":true}}}},"400":{"description":"Invalid query parameter (e.g. limit out of range)"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"}}},"put":{"x-resource-group":"accounts","operationId":"updateGmbLocation","tags":["Connect"],"summary":"Update Google Business Profile location","description":"Switch which Google Business Profile location is active for a connected account.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["selectedLocationId"],"properties":{"selectedLocationId":{"type":"string","minLength":1},"googleAccountId":{"type":"string","minLength":1,"description":"Optional but recommended. The Google Business Profile Account resource name (\"accounts/123\") that owns the new location (from GET gmb-locations).\n\nWhen provided, the location is resolved directly instead of by enumerating the account, which is required for accounts with many locations.\n\nNamed `googleAccountId` to disambiguate from the path `accountId` (the Zernio account). The legacy field name `accountId` is still accepted for backwards compatibility.\n"}}},"example":{"selectedLocationId":"12345678901234567890","googleAccountId":"accounts/123456789"}}}},"responses":{"200":{"description":"Location updated","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"selectedLocation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}},"example":{"message":"Google Business location updated successfully","selectedLocation":{"id":"12345678901234567890","name":"My Business Location"}}}}},"400":{"description":"Location not in available locations, or the provided googleAccountId is not one of the accounts this connection manages"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"},"409":{"description":"Another account on this profile is already connected to that destination (profile_platform_conflict).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/accounts/{accountId}/gmb-locations/assign":{"post":{"x-resource-group":"accounts","operationId":"assignGoogleBusinessLocation","tags":["Connect"],"summary":"Assign Google Business Profile location to another profile","description":"Connect a Google Business Profile location onto a DIFFERENT profile by reusing the OAuth grant from an already-connected Google Business Profile account, with no browser and no re-authorization.\n\nBuilt for agencies whose single Google account has manager access to many client locations and who run one profile per client:\n\n1. Connect one location the normal way (browser OAuth).\n2. Bulk-assign the rest onto each client's profile via this endpoint.\n\n### Parameters\n\n- The path `accountId` is a SOURCE connected Google Business Profile account (the token holder).\n- The body `profileId` is the TARGET profile, which may already hold other locations.\n\nAssigning a location the target profile already holds refreshes that account.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"A source connected Google Business Profile account whose OAuth grant is reused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","selectedLocationId"],"properties":{"profileId":{"type":"string","description":"Target profile to connect the location onto."},"selectedLocationId":{"type":"string","description":"The Google Business Profile location ID to assign (e.g. \"locations/123\")."},"googleAccountId":{"type":"string","description":"Optional but recommended. The Google Business Profile Account resource name (\"accounts/123\") that owns the location (from GET gmb-locations). When provided the location is resolved directly instead of by enumerating the account, required for accounts with many locations.\n"}}},"example":{"profileId":"507f1f77bcf86cd799439011","selectedLocationId":"locations/12345678901234567890","googleAccountId":"accounts/123456789"}}}},"responses":{"200":{"description":"Location assigned to the target profile","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"account":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string"},"username":{"type":"string"},"displayName":{"type":"string"},"isActive":{"type":"boolean"},"selectedLocationName":{"type":"string","description":"Human-readable location display name (e.g. \"Snap Fitness Dianella\"), NOT a resource name. Do not use it to build API paths."},"selectedLocationId":{"type":"string","description":"Bare Google Business Profile location id (digits only). Combine with the Google Business Profile account id as accounts/{gbpAccountId}/locations/{selectedLocationId} to form the location resource names that gmb-reviews/batch expects in locationNames."}}}}},"example":{"message":"Google Business location assigned to profile successfully","account":{"accountId":"6a41f0ab70e2d329a7741307","platform":"googlebusiness","username":"Snap Fitness Dianella","displayName":"Snap Fitness Dianella","isActive":true,"selectedLocationName":"Snap Fitness Dianella","selectedLocationId":"12345678901234567890"}}}}},"400":{"x-summary":"The body is invalid, the location is not under the Google account, or the googleAccountId is not managed here: fix the request.","description":"Invalid body, selected location not found under the Google account, or the provided googleAccountId is not one of the accounts this connection manages"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Payment required, or target profile exceeds plan limit"},"404":{"description":"Source Google Business Profile account not found"},"409":{"description":"Conflict with an existing connection"}}}},"/v1/accounts/{accountId}/facebook-post-reactions":{"get":{"x-resource-group":"analytics","operationId":"getFacebookPostReactions","tags":["Analytics"],"summary":"Get Facebook post reactions","description":"Returns the reaction breakdown for a Facebook Page post: a count per reaction type\nplus the overall total.\n\nThe whole breakdown is fetched in a single Graph call. The post analytics\nendpoint reports only an aggregate reaction count (surfaced there as `likes`), so use\nthis endpoint when you need per-type counts.\n","parameters":[{"name":"accountId","in":"path","required":true,"description":"The ID of the Facebook Page account","schema":{"type":"string"}},{"name":"postId","in":"query","required":true,"description":"The Facebook post ID","schema":{"type":"string"},"example":"1234567890_9876543210"}],"responses":{"200":{"description":"Reaction breakdown for the post","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string","example":"facebook"},"username":{"type":"string"},"postId":{"type":"string"},"total":{"type":"integer","description":"Total reactions across all types"},"breakdown":{"type":"object","description":"Count per reaction type. A type with no reactions returns 0.","properties":{"like":{"type":"integer"},"love":{"type":"integer"},"haha":{"type":"integer"},"wow":{"type":"integer"},"sad":{"type":"integer"},"angry":{"type":"integer"},"care":{"type":"integer"}}},"lastUpdated":{"type":"string","format":"date-time"}}},"example":{"accountId":"60f7a1b2c3d4e5f6a7b8c9d0","platform":"facebook","username":"My Page","postId":"1234567890_9876543210","total":28,"breakdown":{"like":10,"love":5,"haha":4,"wow":3,"sad":2,"angry":1,"care":3},"lastUpdated":"2026-07-09T09:43:50.000Z"}}}},"400":{"description":"Invalid accountId format, not a Facebook account, or missing postId parameter"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"},"502":{"description":"Facebook rejected the request"}}}},"/v1/accounts/{accountId}/facebook-visitor-posts":{"get":{"x-resource-group":"analytics","operationId":"listFacebookVisitorPosts","x-platforms":["facebook"],"tags":["Analytics"],"summary":"List visitor posts on a Facebook Page","description":"Returns the posts other people published on the connected Facebook Page, newest first. A Page without visitor posts returns an empty `data` array.\n\n### What is returned\n\nZernio reads the Page feed (Graph `/{page-id}/feed`, which works on New Pages Experience Pages, unlike the deprecated `visitor_posts` edge). It drops:\n\n- the posts the Page published itself\n- the posts other people published on their own timeline that only tag the Page\n\n### Pagination\n\nCursor-paginated: pass `nextCursor` from the previous response as `cursor` to read the next page.\n\n`limit` sets how many feed entries are scanned, so a page can hold fewer posts than `limit`, or none, while `nextCursor` is not null. `nextCursor` is null when there are no more pages, and the final page can come back empty.\n\n### Requirements\n\nWorks on `facebook` accounts with a Page selected. Meta requires the `pages_read_user_content` permission, which Zernio requests with the comments scope. An account connected without it receives Meta's refusal as `platform_api_error`.\n","parameters":[{"name":"accountId","in":"path","required":true,"description":"The ID of a connected Facebook Page account.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Number of Page feed entries to scan. The Page's own posts are dropped from them.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","minLength":1,"maxLength":4096}}],"responses":{"200":{"description":"One page of visitor posts","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FacebookVisitorPost"}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to read the next page. Null when there are no more pages."}}},"example":{"data":[{"id":"108765432101234_900000000000001","message":"Love this page","createdTime":"2026-10-20T08:00:00+0000","from":{"id":"27000000000001","name":"Jane Visitor"},"permalinkUrl":"https://www.facebook.com/108765432101234/posts/900000000000001","media":null}],"nextCursor":"QVFIUa"}}}},"400":{"x-summary":"A parameter is invalid, the account is on another platform, or Meta refused the request, for example over a missing permission.","description":"Invalid accountId, limit or cursor, an account on another platform (`platform_not_supported`), or Meta refused the request (`platform_api_error`, for example the Page was connected without the `pages_read_user_content` permission).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is not scoped to this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The account is not reachable by the caller (`account_not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"x-summary":"The connection has no Facebook Page selected: select a Page or reconnect the account.","description":"The connection has no Facebook Page selected (`linked_account_required`). Select a Page or reconnect the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/accounts/{accountId}/facebook-tagged-posts":{"get":{"x-resource-group":"analytics","operationId":"listFacebookTaggedPosts","tags":["Analytics"],"summary":"List the posts a Facebook Page is tagged in","description":"Returns the public posts where other people or Pages tagged the connected\nFacebook Page, as Meta returns them from the Page's `tagged` edge.\n\nCursor-paginated: pass `nextCursor` from the previous response as\n`cursor` to read the next page. `nextCursor` is null when there are no\nmore pages. Meta does not say whether a page is the last one, so the\nfinal page can come back empty with `nextCursor` null.\n\nWorks for `facebook` accounts with a Page selected. Meta needs the\n`pages_read_user_content` permission on the connection: a connection\nmade without it gets Meta's refusal back as `platform_api_error`, and\nreconnecting the account grants it.\n","parameters":[{"name":"accountId","in":"path","required":true,"description":"The ID of a connected Facebook account.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","minLength":1,"maxLength":1000}}],"responses":{"200":{"description":"One page of posts the Page is tagged in","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FacebookTaggedPost"}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to read the next page. Null when there are no more pages."}}}}}},"400":{"x-summary":"A parameter is invalid, the account is on another platform, or Meta refused the request, for example over a missing permission.","description":"Invalid accountId, limit or cursor, an account on another platform (`platform_not_supported`), or Meta refused the request (`platform_api_error`, for example a missing `pages_read_user_content` permission).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is not scoped to this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The account is not reachable by the caller (`account_not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"x-summary":"The connection has no Facebook Page selected: select a Page or reconnect the account.","description":"The connection has no Facebook Page selected (`linked_account_required`). Select a Page or reconnect the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/accounts/{accountId}/reddit-subreddits":{"get":{"x-resource-group":"accounts","operationId":"getRedditSubreddits","tags":["Connect"],"summary":"List Reddit subreddits","description":"Temporarily unavailable: Reddit has blocked third-party apps from its API, so this endpoint returns 503 `PLATFORM_DISABLED` until Reddit restores access. Reddit Ads is not affected.\n\nReturns the subreddits the connected Reddit account can post to. Use this to get a subreddit name when creating a Reddit post.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Subreddits list","content":{"application/json":{"schema":{"type":"object","properties":{"subreddits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Reddit subreddit ID"},"name":{"type":"string","description":"Subreddit name without r/ prefix"},"title":{"type":"string","description":"Subreddit title"},"url":{"type":"string","description":"Subreddit URL path"},"over18":{"type":"boolean","description":"Whether the subreddit is NSFW"}}}},"defaultSubreddit":{"type":"string","description":"Currently set default subreddit for posting"}}},"example":{"subreddits":[{"id":"2qh1i","name":"marketing","title":"Marketing","url":"/r/marketing/","over18":false},{"id":"2qh3l","name":"socialmedia","title":"Social Media","url":"/r/socialmedia/","over18":false}],"defaultSubreddit":"marketing"}}}},"400":{"description":"Not a Reddit account"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"},"503":{"description":"Organic Reddit is temporarily unavailable while Reddit blocks third-party API access (`PLATFORM_DISABLED`)."}}},"put":{"x-resource-group":"accounts","operationId":"updateRedditSubreddits","tags":["Connect"],"summary":"Set default subreddit","description":"Temporarily unavailable: Reddit has blocked third-party apps from its API, so this endpoint returns 503 `PLATFORM_DISABLED` until Reddit restores access. Reddit Ads is not affected.\n\nSets the default subreddit used when publishing posts for this Reddit account.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["defaultSubreddit"],"properties":{"defaultSubreddit":{"type":"string","minLength":1}}},"example":{"defaultSubreddit":"marketing"}}}},"responses":{"200":{"description":"Default subreddit set","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"},"503":{"description":"Organic Reddit is temporarily unavailable while Reddit blocks third-party API access (`PLATFORM_DISABLED`)."}}}},"/v1/accounts/{accountId}/reddit-subreddits/{subreddit}/rules":{"get":{"x-resource-group":"accounts","operationId":"getSubredditRules","tags":["Connect"],"summary":"Get subreddit rules","description":"Temporarily unavailable: Reddit has blocked third-party apps from its API, so this endpoint returns 503 `PLATFORM_DISABLED` until Reddit restores access. Reddit Ads is not affected.\n\nReturns a subreddit's posting rules plus Reddit's site-wide rules, so you can check\nthem before submitting and avoid a removal.\n\nUse this alongside `GET /v1/tools/validate/subreddit`, which only confirms that a\nsubreddit exists and reports its basic posting settings.\n","parameters":[{"name":"accountId","in":"path","required":true,"description":"The ID of the Reddit account","schema":{"type":"string"}},{"name":"subreddit","in":"path","required":true,"description":"Subreddit name (without the \"r/\" prefix)","schema":{"type":"string"},"example":"webdev"}],"responses":{"200":{"description":"Subreddit and site rules","content":{"application/json":{"schema":{"type":"object","properties":{"rules":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","description":"Scope of the rule: 'link', 'comment', or 'all'"},"shortName":{"type":"string","description":"Short rule title shown in the subreddit sidebar"},"description":{"type":"string","description":"Full rule text"},"violationReason":{"type":"string","description":"Reason shown to a user when the rule is enforced"},"createdUtc":{"type":"number","description":"Unix timestamp when the rule was created"},"priority":{"type":"integer","description":"Display order of the rule"}}}},"siteRules":{"type":"array","description":"Reddit's site-wide content policy rules","items":{"type":"string"}}}},"example":{"rules":[{"kind":"link","shortName":"No self-promotion","description":"Posts that primarily promote your own product will be removed.","violationReason":"Self-promotion","createdUtc":1611234567,"priority":0}],"siteRules":["Spam","Personal and confidential information"]}}}},"400":{"description":"Not a Reddit account"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account or subreddit not found"},"502":{"x-summary":"Reddit was unreachable or returned an unclassified error: retry later, and note that Reddit 4xx statuses pass through unchanged.","description":"Reddit was unreachable or returned an unclassified error. Reddit 4xx statuses are forwarded as-is."},"503":{"description":"Organic Reddit is temporarily unavailable while Reddit blocks third-party API access (`PLATFORM_DISABLED`)."}}}},"/v1/accounts/{accountId}/reddit-vote":{"post":{"x-resource-group":"engagement","operationId":"voteRedditThing","tags":["Connect"],"summary":"Vote on a Reddit post or comment","description":"Temporarily unavailable: Reddit has blocked third-party apps from its API, so this endpoint returns 503 `PLATFORM_DISABLED` until Reddit restores access. Reddit Ads is not affected.\n\nCast, change, or clear the connected account's vote on a Reddit post or comment.\n\n### Reddit requires that votes be cast by humans\n\nReddit's API terms permit a client to proxy a human's action one-for-one, and prohibit a bot from deciding how to vote or from amplifying a human's vote.\n\nCall this endpoint only in direct response to an explicit action by the account owner. Automated or agent-decided voting is vote manipulation and puts API access at risk.\n","parameters":[{"name":"accountId","in":"path","required":true,"description":"The ID of the Reddit account casting the vote","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["thingId","direction"],"properties":{"thingId":{"type":"string","description":"Reddit fullname of the target. Prefix \"t3_\" for a post and \"t1_\" for a comment. A bare id with no prefix is treated as a post (\"t3_\").\n","example":"t3_abc123"},"direction":{"type":"integer","description":"1 to upvote, -1 to downvote, 0 to clear an existing vote","enum":[1,0,-1]}}},"example":{"thingId":"t3_abc123","direction":1}}}},"responses":{"200":{"description":"Vote registered","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"400":{"description":"Not a Reddit account, or invalid thingId/direction"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"},"502":{"x-summary":"Reddit was unreachable or returned an unclassified error: retry later, and note that Reddit 4xx statuses pass through unchanged.","description":"Reddit was unreachable or returned an unclassified error. Reddit 4xx statuses are forwarded as-is."},"503":{"description":"Organic Reddit is temporarily unavailable while Reddit blocks third-party API access (`PLATFORM_DISABLED`)."}}}},"/v1/accounts/{accountId}/reddit-flairs":{"get":{"x-resource-group":"accounts","operationId":"getRedditFlairs","tags":["Connect"],"summary":"List subreddit flairs","description":"Temporarily unavailable: Reddit has blocked third-party apps from its API, so this endpoint returns 503 `PLATFORM_DISABLED` until Reddit restores access. Reddit Ads is not affected.\n\nReturns available post flairs for a subreddit. Some subreddits require a flair when posting.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"subreddit","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Subreddit name (without \"r/\" prefix) to fetch flairs for"}],"responses":{"200":{"description":"Flairs list","content":{"application/json":{"schema":{"type":"object","properties":{"flairs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Flair ID to pass as flairId in platformSpecificData"},"text":{"type":"string","description":"Flair display text"},"textColor":{"type":"string","description":"Text color: 'dark' or 'light'"},"backgroundColor":{"type":"string","description":"Background hex color (e.g. '#ff4500')"}}}}}},"example":{"flairs":[{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","text":"Discussion","textColor":"dark","backgroundColor":"#edeff1"},{"id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","text":"News","textColor":"light","backgroundColor":"#ff4500"}]}}}},"400":{"description":"Not a Reddit account or missing subreddit parameter"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"},"503":{"description":"Organic Reddit is temporarily unavailable while Reddit blocks third-party API access (`PLATFORM_DISABLED`)."}}},"post":{"x-resource-group":"accounts","operationId":"setRedditPostFlair","tags":["Connect"],"summary":"Set Reddit post flair","description":"Temporarily unavailable: Reddit has blocked third-party apps from its API, so this endpoint returns 503 `PLATFORM_DISABLED` until Reddit restores access. Reddit Ads is not affected.\n\nApplies a flair to a post the connected account already published. Use the GET on this\npath to list the available `flairTemplateId` values for the subreddit.\n\nFlair can also be set at submit time by passing `flairId` in `platformSpecificData`\nwhen creating the post. This endpoint is for changing it afterwards.\n\nThe subreddit must allow users to select their own post flair. Setting flair on\nanother user's post requires moderator permissions, which Zernio does not request.\n","parameters":[{"name":"accountId","in":"path","required":true,"description":"The ID of the Reddit account that owns the post","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subreddit","postId","flairTemplateId"],"properties":{"subreddit":{"type":"string","minLength":1,"description":"Subreddit name (without the \"r/\" prefix)"},"postId":{"type":"string","minLength":1,"description":"Reddit post id, with or without the t3_ prefix"},"flairTemplateId":{"type":"string","minLength":1,"description":"Flair template id from the GET on this path"},"text":{"type":"string","description":"Optional override text, only for editable flair templates"}}},"example":{"subreddit":"webdev","postId":"t3_abc123","flairTemplateId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}}},"responses":{"200":{"description":"Flair applied","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"400":{"description":"Not a Reddit account, or missing subreddit/postId/flairTemplateId"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"},"502":{"x-summary":"Reddit was unreachable or returned an unclassified error: retry later, and note that Reddit 4xx statuses pass through unchanged.","description":"Reddit was unreachable or returned an unclassified error. Reddit 4xx statuses (e.g. subreddit does not allow user flair selection) are forwarded as-is."},"503":{"description":"Organic Reddit is temporarily unavailable while Reddit blocks third-party API access (`PLATFORM_DISABLED`)."}}}},"/v1/accounts/{accountId}/hubspot-settings":{"get":{"x-resource-group":"accounts","operationId":"getHubSpotSettings","tags":["Accounts"],"summary":"Get HubSpot account settings","description":"Read a connected HubSpot portal and what Zernio syncs to it.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"HubSpot settings","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"$ref":"#/components/schemas/HubSpotSettings"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"}}},"patch":{"x-resource-group":"accounts","operationId":"updateHubSpotSettings","tags":["Accounts"],"summary":"Update HubSpot account settings","description":"Turn contact sync, message logging or deal reporting on or off for a connected HubSpot portal. Send at least one field; omitted fields keep their value. Settings survive reconnecting the same portal.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"syncContacts":{"type":"boolean","description":"Create a HubSpot contact for an inbox contact that matches none by email or phone. A match is linked as it is and never updated."},"logMessages":{"type":"boolean","description":"Log inbound and outbound inbox messages on the contact's HubSpot timeline."},"reportDeals":{"type":"boolean","description":"Send each deal that becomes closed won as a Purchase to the profile's event destinations, about once an hour. Requires the portal to have granted `crm.objects.deals.read`; otherwise 400. Deals closed before it was turned on are not sent."},"useDealsAsResults":{"type":"boolean","description":"Count each closed-won deal as a sale with its amount on the ad campaign that brought its contact, in `GET /v1/ads/campaign-results` and ad rules. Requires `crm.objects.deals.read`; otherwise 400. Turning it on fills in the deals of the last 90 days, never sent to the ad platforms."}}}}}},"responses":{"200":{"description":"Updated settings","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"account":{"$ref":"#/components/schemas/HubSpotSettings"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"}}}},"/v1/accounts/{accountId}/slack-settings":{"get":{"x-resource-group":"accounts","operationId":"getSlackSettings","tags":["Accounts"],"summary":"Get Slack account settings","description":"Returns the connected Slack channel details and the default message identity (name and avatar shown as the author on every post, with Slack's APP badge). The identity applies to messages only; the app's own Slack profile is global and cannot be changed per workspace.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Slack account settings","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"object","properties":{"_id":{"type":"string"},"platform":{"type":"string","example":"slack"},"displayName":{"type":["string","null"]},"channelId":{"type":["string","null"]},"channelName":{"type":["string","null"]},"channelType":{"type":["string","null"],"description":"public or private"},"teamId":{"type":["string","null"]},"teamName":{"type":["string","null"]},"defaultUsername":{"type":["string","null"]},"defaultIconUrl":{"type":["string","null"]}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"}}},"patch":{"x-resource-group":"accounts","operationId":"updateSlackSettings","tags":["Accounts"],"summary":"Update Slack account settings","description":"Set or clear the default message identity for this channel. Empty string clears a field; per-post platformSpecificData.username/iconUrl still override these defaults.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"defaultUsername":{"type":"string","maxLength":80,"description":"Author name shown on posts. Empty string clears it."},"defaultIconUrl":{"type":"string","description":"Author avatar image URL. Empty string clears it."},"applyToWorkspace":{"type":"boolean","default":false,"description":"Applies the name and icon to every connected channel of this Slack workspace owned by the same owner, on the same Slack app, in profiles the caller can access. Channels connected later inherit the identity from a channel of that workspace."}}}}}},"responses":{"200":{"description":"Updated settings"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"}}}},"/v1/accounts/{accountId}/bluesky-settings":{"get":{"x-resource-group":"accounts","operationId":"getBlueskySettings","tags":["Accounts"],"summary":"Get Bluesky account settings","description":"Returns the account's default post languages (defaultLangs), applied at publish time whenever a post's platformSpecificData.langs is absent. Null when no default is set.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Bluesky account settings","content":{"application/json":{"schema":{"type":"object","properties":{"defaultLangs":{"type":["array","null"],"items":{"type":"string"},"example":["pt"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"}}},"patch":{"x-resource-group":"accounts","operationId":"updateBlueskySettings","tags":["Accounts"],"summary":"Update Bluesky account settings","description":"Set or clear the account's default post languages. 1-3 BCP-47 codes (e.g. \"pt\", \"en-US\"), the same validation as per-post langs; explicit null clears the default. Per-post platformSpecificData.langs always overrides this default. Applies to posts published after the change; already-published posts cannot be retagged (Bluesky has no post edit).","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["defaultLangs"],"properties":{"defaultLangs":{"type":["array","null"],"minItems":1,"maxItems":3,"items":{"type":"string"},"example":["pt"]}}}}}},"responses":{"200":{"description":"Updated settings"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"}}}},"/v1/accounts/{accountId}/discord-settings":{"get":{"x-resource-group":"accounts","operationId":"getDiscordSettings","tags":["Discord"],"summary":"Get Discord account settings","description":"Returns the current Discord account settings including webhook identity (display name and avatar), connected channel, and guild information.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Discord account settings","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"object","properties":{"_id":{"type":"string"},"platform":{"type":"string","example":"discord"},"username":{"type":"string","description":"Channel name"},"displayName":{"type":"string","description":"Guild - #channel display name"},"profilePicture":{"type":"string","description":"Guild icon URL"},"channelId":{"type":"string","description":"Connected channel snowflake ID"},"channelName":{"type":"string","description":"Channel name"},"channelType":{"type":"string","description":"Channel type (0 = text, 5 = announcement, 15 = forum)"},"guildId":{"type":"string","description":"Guild (server) snowflake ID"},"webhookUsername":{"type":["string","null"],"description":"Custom webhook display name (null = default \"Zernio\")"},"webhookAvatarUrl":{"type":["string","null"],"description":"Custom webhook avatar URL (null = default bot avatar)"}}}}},"example":{"account":{"_id":"abc123","platform":"discord","username":"announcements","displayName":"My Server - #announcements","profilePicture":"https://cdn.discordapp.com/icons/123/abc.png","channelId":"1234567890123456789","channelName":"announcements","channelType":"0","guildId":"9876543210987654321","webhookUsername":"My Brand","webhookAvatarUrl":"https://example.com/logo.png"}}}}},"400":{"description":"Not a Discord account"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"}}},"patch":{"x-resource-group":"accounts","operationId":"updateDiscordSettings","tags":["Discord"],"summary":"Update Discord settings","description":"Update Discord account settings. Supports two operations (can be combined):\n\n1. **Webhook identity** - Set the default display name and avatar that appear as the message author on every post. These are account-level defaults; individual posts can override them via platformSpecificData.webhookUsername / webhookAvatarUrl.\n\n2. **Switch channel** - Move the connection to a different channel in the same guild. A new webhook is automatically created in the target channel.\n","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"webhookUsername":{"type":"string","description":"Custom display name for the webhook (1-80 chars). Empty string resets to default (\"Zernio\"). Cannot contain \"clyde\" or \"discord\"."},"webhookAvatarUrl":{"type":"string","description":"Custom avatar URL. Empty string resets to default bot avatar. Zernio upload URLs (temp/) are copied to permanent storage; an expired one returns 400."},"channelId":{"type":"string","description":"Switch to a different channel in the same guild. Must be a text (0), announcement (5), or forum (15) channel."}}},"examples":{"identity":{"summary":"Update webhook identity","value":{"webhookUsername":"My Brand","webhookAvatarUrl":"https://example.com/logo.png"}},"channel":{"summary":"Switch channel","value":{"channelId":"9999999999999999999"}}}}}},"responses":{"200":{"description":"Settings updated","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Discord settings updated"},"account":{"type":"object","properties":{"_id":{"type":"string"},"platform":{"type":"string"},"username":{"type":"string"},"displayName":{"type":"string"},"profilePicture":{"type":"string"},"channelId":{"type":"string"},"channelName":{"type":"string"},"channelType":{"type":"string"},"guildId":{"type":"string"},"webhookUsername":{"type":["string","null"]},"webhookAvatarUrl":{"type":["string","null"]}}}}}}}},"400":{"description":"Invalid request (no changes, invalid channel type, or bot cannot access channel)"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Discord account not found"}}}},"/v1/accounts/{accountId}/discord-channels":{"get":{"x-resource-group":"accounts","operationId":"getDiscordChannels","tags":["Discord"],"summary":"List Discord guild channels","description":"Returns the text, announcement, and forum channels in the connected Discord guild. Use this to discover available channels when switching the connected channel via PATCH /v1/accounts/{accountId}/discord-settings.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Channel list","content":{"application/json":{"schema":{"type":"object","properties":{"channels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Channel snowflake ID"},"name":{"type":"string","description":"Channel name"},"type":{"type":"integer","description":"Channel type: 0 (text), 5 (announcement), 15 (forum)"}}}}}},"example":{"channels":[{"id":"1234567890123456789","name":"general","type":0},{"id":"2345678901234567890","name":"announcements","type":5},{"id":"3456789012345678901","name":"feedback","type":15}]}}}},"400":{"description":"Not a Discord account or missing guild info"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"}}}},"/v1/accounts/{accountId}/slack-members":{"get":{"x-resource-group":"contacts","operationId":"listSlackMembers","tags":["Slack"],"summary":"List Slack workspace members","description":"Members of the connected Slack workspace that can receive a direct message, for populating a recipient picker. Bots, deactivated members and Slackbot are excluded. Start a DM by passing a member id as `participantId` to POST /v1/inbox/conversations.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"query","in":"query","required":false,"description":"Case-insensitive filter over display name and handle.","schema":{"type":"string","maxLength":100}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":2000,"default":50}}],"responses":{"200":{"description":"Workspace members","content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Slack member id (pass as participantId to start a DM)."},"name":{"type":"string","description":"Display name"},"username":{"type":["string","null"],"description":"Slack handle"},"picture":{"type":["string","null"],"description":"Avatar URL"}}}}}},"example":{"members":[{"id":"U01ABCDEF","name":"Maria García","username":"maria","picture":"https://avatars.slack-edge.com/maria.png"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Slack account not found"}}}},"/v1/discord/dms":{"post":{"x-resource-group":"messages","operationId":"sendDiscordDirectMessage","tags":["Discord"],"summary":"Send a Discord Direct Message","description":"Send a 1:1 Direct Message from the bot to a Discord user (by snowflake ID). Supports the same payload shape as channel posts: content, embeds, media attachments, and TTS.\n\n### Constraints (Discord platform limits)\n\n- The bot can only DM users it shares at least one guild with.\n- If the recipient has DMs disabled for non-friends, Discord returns 403 (surfaces as a 502 platform error).\n- `content` capped at 2,000 chars.\n- At least one of `content`, `embeds`, or `attachments` is required.\n- The recipient must be identified by Discord snowflake ID (not username).\n\n### Why a separate endpoint\n\nThis is a dedicated endpoint rather than a `POST /v1/posts` variant because DMs are 1:1 operational messages (onboarding, billing reminders, support pings) with a different lifecycle than scheduled channel posts.\n\nDMs are not persisted to `Post` / `ExternalPost` and are always sent immediately.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","userId"],"properties":{"accountId":{"type":"string","description":"SocialAccount _id of the connected Discord account the bot speaks as. Caller must own the account (directly or via team membership).","example":"65a1b2c3d4e5f60718293a4b"},"userId":{"type":"string","description":"Discord snowflake ID of the recipient (15-21 digits).","example":"1234567890123456789"},"content":{"type":"string","description":"Message text, up to 2,000 characters.","maxLength":2000},"embeds":{"type":"array","description":"Up to 10 Discord embeds. Same shape as channel-post embeds (title, description, color, fields, etc.). See DiscordPlatformData.embeds for the embed object schema.","maxItems":10,"items":{"type":"object"}},"attachments":{"type":"array","description":"Up to 10 media attachments. Each is `{ type: image|video|gif|document, url, filename?, mimeType?, size? }`.","maxItems":10,"items":{"type":"object","required":["type","url"],"properties":{"type":{"type":"string","enum":["image","video","gif","document"]},"url":{"type":"string","format":"uri"},"filename":{"type":"string"},"mimeType":{"type":"string"},"size":{"type":"integer"}}}},"tts":{"type":"boolean","description":"Send as text-to-speech message."}}},"example":{"accountId":"65a1b2c3d4e5f60718293a4b","userId":"1234567890123456789","content":"Welcome to Acme! Reply STOP to opt out."}}}},"responses":{"200":{"description":"DM sent successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"messageId":{"type":"string","description":"Discord message snowflake ID"},"channelId":{"type":"string","description":"DM channel snowflake (Discord auto-creates one per recipient pair)"},"url":{"type":"string","description":"Direct link to the message, using Discord's @me path for DMs"},"timestamp":{"type":"string","format":"date-time"},"recipient":{"type":"object","properties":{"userId":{"type":"string"},"platform":{"type":"string","example":"discord"}}},"account":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string"},"displayName":{"type":"string"}}}}},"example":{"messageId":"1357924680135792468","channelId":"1357924680135792467","url":"https://discord.com/channels/@me/1357924680135792467/1357924680135792468","timestamp":"2026-06-02T12:34:56.789Z","recipient":{"userId":"1234567890123456789","platform":"discord"},"account":{"id":"65a1b2c3d4e5f60718293a4b","username":"announcements","displayName":"My Server - #announcements"}}}}},"400":{"description":"Validation error (missing required fields, content > 2000 chars, malformed snowflake, or all of content/embeds/attachments missing)."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Discord refused the message, usually because the bot shares no guild with the recipient or the recipient disabled DMs.","description":"Discord refused the message (most commonly: bot doesn't share a guild with the recipient, OR the recipient has DMs disabled). Error body contains Discord's response."},"404":{"description":"Discord account not found or not accessible to this user."},"502":{"description":"Discord was unreachable or returned an unclassified error."}}}},"/v1/discord/guilds/{guildId}/roles":{"get":{"x-resource-group":"engagement","operationId":"listDiscordGuildRoles","tags":["Discord"],"summary":"List Discord guild roles","description":"Returns all roles in a Discord guild. Useful for building role-mention\npickers, role-permission UIs, or finding the role ID before calling\nthe role-assign endpoint.\n\nRoles are returned unordered. Sort client-side by `position` if you\nneed Discord's UI ordering.\n\nCaller must pass `accountId` of a Discord SocialAccount bound to this\nguild (route verifies team access + guild match).\n","parameters":[{"name":"guildId","in":"path","required":true,"schema":{"type":"string"},"description":"Discord guild snowflake ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"SocialAccount _id of the Discord account bound to this guild"}],"responses":{"200":{"description":"List of guild roles.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","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"}}}}}}}}},"400":{"description":"Invalid accountId or guildId format."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Discord refused the request (bot lacks View Channels permission in the guild)."},"404":{"description":"Discord account not found, not accessible, or not bound to this guild."},"502":{"description":"Discord was unreachable or returned an unclassified error."}}},"post":{"x-resource-group":"engagement","operationId":"createDiscordGuildRole","tags":["Discord"],"summary":"Create a Discord guild role","description":"Creates a new role in the guild.\n\nRequires the bot to hold the Manage Roles permission. Guilds that added the Zernio bot\nbefore role management shipped must re-invite it, because Discord applies the\npermission set at invite time.\n\nDiscord's role hierarchy applies: the bot cannot create a role positioned at or above\nits own highest role, and cannot grant permissions it does not itself hold. Either\nattempt returns a 403 carrying Discord's own error.\n","parameters":[{"name":"guildId","in":"path","required":true,"schema":{"type":"string"},"description":"Discord guild snowflake ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"SocialAccount _id of the Discord account bound to this guild"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"color":{"type":"integer","minimum":0,"maximum":16777215,"description":"Decimal color (0 = no color). 0xFF0000 red is 16711680."},"hoist":{"type":"boolean","description":"Display members with this role separately in the member list"},"mentionable":{"type":"boolean","description":"Allow anyone to @mention this role"},"permissions":{"type":"string","description":"Permissions bitfield as a stringified integer"}}},"example":{"name":"Moderators","color":16711680,"hoist":true,"mentionable":false}}}},"responses":{"201":{"description":"Role created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DiscordRole"}}}}}},"400":{"description":"Invalid accountId, guildId, or role body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Discord refused the action (bot lacks Manage Roles, or the new role would sit at or above the bot's highest role)."},"404":{"description":"Discord account not found, not accessible, or not bound to this guild."},"502":{"description":"Discord was unreachable or returned an unclassified error."}}}},"/v1/discord/guilds/{guildId}/roles/{roleId}":{"patch":{"x-resource-group":"engagement","operationId":"editDiscordGuildRole","tags":["Discord"],"summary":"Edit a Discord guild role","description":"Updates a role's name, color, hoist, mentionable flag, or permission bitfield.\nAt least one field must be supplied. Omitted fields are left unchanged.\n\nRequires the bot to hold Manage Roles, and the target role must sit below the bot's\nhighest role. See the create-role operation for the re-invite requirement.\n","parameters":[{"name":"guildId","in":"path","required":true,"schema":{"type":"string"},"description":"Discord guild snowflake ID"},{"name":"roleId","in":"path","required":true,"schema":{"type":"string"},"description":"Discord role snowflake ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"SocialAccount _id of the Discord account bound to this guild"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"color":{"type":"integer","minimum":0,"maximum":16777215},"hoist":{"type":"boolean"},"mentionable":{"type":"boolean"},"permissions":{"type":"string","description":"Permissions bitfield as a stringified integer"}}},"example":{"name":"Senior Moderators","mentionable":true}}}},"responses":{"200":{"description":"Role updated.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DiscordRole"}}}}}},"400":{"description":"Invalid ids, or no fields supplied to edit."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Discord refused the action (bot lacks Manage Roles, or the target role sits at or above the bot's highest role)."},"404":{"description":"Discord account not found, not accessible, or not bound to this guild."},"502":{"description":"Discord was unreachable or returned an unclassified error."}}},"delete":{"x-resource-group":"engagement","operationId":"deleteDiscordGuildRole","tags":["Discord"],"summary":"Delete a Discord guild role","description":"Permanently deletes a role from the guild and removes it from every member.\nThis cannot be undone.\n\nRequires the bot to hold Manage Roles, and the target role must sit below the bot's\nhighest role.\n","parameters":[{"name":"guildId","in":"path","required":true,"schema":{"type":"string"},"description":"Discord guild snowflake ID"},{"name":"roleId","in":"path","required":true,"schema":{"type":"string"},"description":"Discord role snowflake ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"SocialAccount _id of the Discord account bound to this guild"}],"responses":{"200":{"description":"Role deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"400":{"description":"Invalid accountId, guildId, or roleId format."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Discord refused the action (bot lacks Manage Roles, or the target role sits at or above the bot's highest role)."},"404":{"description":"Discord account not found, not accessible, or not bound to this guild."},"502":{"description":"Discord was unreachable or returned an unclassified error."}}}},"/v1/discord/guilds/{guildId}/members":{"get":{"x-resource-group":"contacts","operationId":"listDiscordGuildMembers","tags":["Discord"],"summary":"List Discord guild members","description":"Cursor-paginated list of guild members. Returns Discord's raw member\nobjects so callers can build community-ops automation (e.g. \"add role\nto all members joined in the last 7 days\") on the actual platform shape.\n\nPagination: pass `after` = the last `user.id` from the previous page.\nOmit on the first call. Response includes a `nextCursor` and `hasMore`\nflag so callers don't need to know Discord's pagination shape.\n","parameters":[{"name":"guildId","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"Page size (1-1000)."},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"Snowflake of the last member from the previous page."}],"responses":{"200":{"description":"List of guild members.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DiscordGuildMember"}},"pagination":{"type":"object","properties":{"nextCursor":{"type":["string","null"],"description":"Pass as `after` on the next call. Null when there are no more pages."},"hasMore":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid query params."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Discord denied access to the guild members (the bot is no longer in the guild)."},"404":{"description":"Discord account not found or not in this guild."}}}},"/v1/discord/guilds/{guildId}/members/search":{"get":{"x-resource-group":"contacts","operationId":"searchDiscordGuildMembers","tags":["Discord"],"summary":"Search Discord guild members","description":"Search guild members whose username or nickname **starts with** the\nquery (Discord matches prefixes only, not substrings).\n\nCheaper than paginating the full member listing when you already know\nwho you are looking for.\n","parameters":[{"name":"guildId","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":100},"description":"Username or nickname prefix to match."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":25}}],"responses":{"200":{"description":"Matching guild members.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DiscordGuildMember"}}}}}}},"400":{"description":"Invalid query params."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Discord account not found or not in this guild."}}}},"/v1/discord/guilds/{guildId}/members/{userId}":{"get":{"x-resource-group":"contacts","operationId":"getDiscordGuildMember","tags":["Discord"],"summary":"Get a Discord guild member","description":"Fetch a single guild member by Discord user id.\n\nCheaper than paginating the full member listing when you already know\nwho you are looking for.\n","parameters":[{"name":"guildId","in":"path","required":true,"schema":{"type":"string"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"Discord user snowflake."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The guild member.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DiscordGuildMember"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Discord account not found, or the user is not a member of this guild."}}}},"/v1/discord/guilds/{guildId}/members/{userId}/roles/{roleId}":{"put":{"x-resource-group":"contacts","operationId":"addDiscordMemberRole","tags":["Discord"],"summary":"Assign a role to a guild member","description":"Assign one role to one member. Idempotent on Discord's side: re-running\non a member who already has the role is a 204 no-op.\n\nPath shape mirrors Discord's own API (`PUT /guilds/{guild}/members/{user}/roles/{role}`)\nfor zero-translation mental mapping.\n\nBot needs MANAGE_ROLES permission in the guild AND its highest role\nmust be above the target role (Discord hierarchy rule). The\n`@everyone` role (where roleId == guildId) cannot be assigned.\n","parameters":[{"name":"guildId","in":"path","required":true,"schema":{"type":"string"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"Discord user snowflake to assign the role to."},{"name":"roleId","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Role assigned (or already present, idempotent).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"operation":{"type":"string","enum":["role_assigned"]},"guildId":{"type":"string"},"userId":{"type":"string"},"roleId":{"type":"string"}}}}}},"400":{"description":"Validation error (malformed snowflake) or @everyone manipulation attempt."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Discord refused the request: bot lacks MANAGE_ROLES, or target role is at or above the bot's highest role."},"404":{"description":"Discord account not found or not in this guild."},"502":{"description":"Discord was unreachable or returned an unclassified error."}}},"delete":{"x-resource-group":"contacts","operationId":"removeDiscordMemberRole","tags":["Discord"],"summary":"Remove a role from a guild member","description":"Remove one role from one member. Idempotent: removing a role the\nmember doesn't have returns 204 no-op.\n\nSame permission + hierarchy constraints as the PUT counterpart.\n","parameters":[{"name":"guildId","in":"path","required":true,"schema":{"type":"string"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string"}},{"name":"roleId","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Role removed (or was already absent, idempotent).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"operation":{"type":"string","enum":["role_removed"]},"guildId":{"type":"string"},"userId":{"type":"string"},"roleId":{"type":"string"}}}}}},"400":{"description":"Validation error."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Discord refused the request (permission or hierarchy issue)."},"404":{"description":"Discord account not found or not in this guild."},"502":{"description":"Discord was unreachable or returned an unclassified error."}}}},"/v1/discord/channels/{channelId}/messages/{messageId}":{"delete":{"x-resource-group":"engagement","operationId":"deleteDiscordMessage","tags":["Discord"],"summary":"Delete a Discord channel message","description":"Deletes a message from a channel, for moderation and cleanup. This cannot be undone.\n\nDeleting a message the bot did not send requires the bot to hold the Manage Messages\npermission, which the Zernio bot requests at install time. Deleting the bot's own\nmessage needs no extra permission.\n\nOwnership is verified by resolving the channel's guild and confirming the caller owns\na Discord account bound to it.\n","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string"},"description":"Discord channel snowflake ID"},{"name":"messageId","in":"path","required":true,"schema":{"type":"string"},"description":"Discord message snowflake ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"SocialAccount _id of the Discord account bound to this channel's guild"}],"responses":{"200":{"description":"Message deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"400":{"description":"Invalid accountId, channelId, or messageId format."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Discord refused the action (bot lacks Manage Messages)."},"404":{"description":"Discord account not found, not accessible, or not bound to this channel's guild."},"502":{"description":"Discord was unreachable or returned an unclassified error."}}}},"/v1/discord/channels/{channelId}/messages/{messageId}/crosspost":{"post":{"x-resource-group":"engagement","operationId":"crosspostDiscordMessage","tags":["Discord"],"summary":"Crosspost Discord message","description":"Publishes a message from an announcement channel so it propagates to every server\nfollowing that channel.\n\nThe source channel must be an announcement channel. Calling this on a regular text\nchannel returns a 400 before Discord is contacted, because Discord's own error for\nthis case is opaque.\n","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string"},"description":"Discord announcement channel snowflake ID"},{"name":"messageId","in":"path","required":true,"schema":{"type":"string"},"description":"Discord message snowflake ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"SocialAccount _id of the Discord account bound to this channel's guild"}],"responses":{"200":{"description":"Message crossposted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"The crossposted Discord message object."}}}}}},"400":{"description":"Invalid ids, or the channel is not an announcement channel."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Discord refused the action (bot lacks the required permission)."},"404":{"description":"Discord account not found, not accessible, or not bound to this channel's guild."},"502":{"description":"Discord was unreachable or returned an unclassified error."}}}},"/v1/discord/channels/{channelId}/threads":{"post":{"x-resource-group":"engagement","operationId":"createDiscordThread","tags":["Discord"],"summary":"Create a Discord public thread","description":"Creates a public thread in a channel. Pass `messageId` to start the thread from an\nexisting message, or omit it to create a standalone thread.\n\nThreads created here are always public. Requires the bot to hold Create Public\nThreads, which the Zernio bot requests at install time.\n","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string"},"description":"Discord channel snowflake ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"SocialAccount _id of the Discord account bound to this channel's guild"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Thread name"},"messageId":{"type":"string","description":"Optional message snowflake to start the thread from. Omit for a standalone thread."},"autoArchiveDuration":{"type":"integer","enum":[60,1440,4320,10080],"description":"Minutes of inactivity before the thread auto-archives. Discord accepts only these four values."}}},"example":{"name":"Release 2.4 discussion","autoArchiveDuration":1440}}}},"responses":{"200":{"description":"Thread created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Thread snowflake ID"},"name":{"type":"string"}}}}},"example":{"data":{"id":"1180000000000000000","name":"Release 2.4 discussion"}}}}},"400":{"description":"Invalid accountId, channelId, messageId, name, or autoArchiveDuration."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Discord refused the action (bot lacks Create Public Threads)."},"404":{"description":"Discord account not found, not accessible, or not bound to this channel's guild."},"502":{"description":"Discord was unreachable or returned an unclassified error."}}}},"/v1/discord/channels/{channelId}/pins":{"get":{"x-resource-group":"engagement","operationId":"listDiscordPinnedMessages","tags":["Discord"],"summary":"List pinned messages","description":"Returns the channel's pinned messages, sorted most-recently-pinned\nfirst. Discord caps a channel at 50 pinned messages and returns the\nfull list unpaginated.\n\nBot needs READ_MESSAGE_HISTORY in the channel (granted by default\nBOT_PERMISSIONS).\n","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string"},"description":"Discord channel snowflake."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"SocialAccount _id of any Discord account in the same guild."}],"responses":{"200":{"description":"Pinned messages.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"Raw Discord Message object. See DiscordPlatformData for embed/attachment shapes.","properties":{"id":{"type":"string"},"channel_id":{"type":"string"},"content":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"author":{"type":"object"},"attachments":{"type":"array","items":{"type":"object"}},"embeds":{"type":"array","items":{"type":"object"}}}}}}}}}},"400":{"description":"Invalid channelId or accountId format."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Discord account not found or not accessible."},"502":{"description":"Bot lacks access to the channel."}}}},"/v1/discord/channels/{channelId}/pins/{messageId}":{"put":{"x-resource-group":"engagement","operationId":"pinDiscordMessage","tags":["Discord"],"summary":"Pin a Discord message","description":"Pin a specific message in a channel. Path shape mirrors Discord's own\nAPI (`PUT /channels/{cid}/pins/{mid}`).\n\nIdempotent: re-pinning an already-pinned message is a 204 no-op.\n\nConstraints:\n  - Bot needs MANAGE_MESSAGES in the channel.\n  - 50-pin cap per channel: hitting it returns 400 (Discord-side).\n    Caller should unpin one first.\n","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string"}},{"name":"messageId","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Message pinned (or was already pinned, idempotent).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"operation":{"type":"string","enum":["message_pinned"]},"channelId":{"type":"string"},"messageId":{"type":"string"}}}}}},"400":{"description":"Validation error or pin cap (50) reached."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Discord account not found."},"502":{"description":"Bot lacks MANAGE_MESSAGES in the channel."}}},"delete":{"x-resource-group":"engagement","operationId":"unpinDiscordMessage","tags":["Discord"],"summary":"Unpin a Discord message","description":"Unpin a message. Same MANAGE_MESSAGES permission requirement as pin.\nIdempotent: unpinning a non-pinned message is a 204 no-op.\n","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string"}},{"name":"messageId","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Message unpinned (or was not pinned, idempotent).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"operation":{"type":"string","enum":["message_unpinned"]},"channelId":{"type":"string"},"messageId":{"type":"string"}}}}}},"400":{"description":"Validation error."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Discord account not found."},"502":{"description":"Bot lacks MANAGE_MESSAGES in the channel."}}}},"/v1/discord/guilds/{guildId}/events":{"get":{"x-resource-group":"engagement","operationId":"listDiscordScheduledEvents","tags":["Discord"],"summary":"List Discord scheduled events","description":"Return all scheduled events in the guild. Events are distinct from\nmessages: they appear in the server's Events panel and Discord\nauto-notifies interested members ahead of start time.\n\nPass `withUserCount=true` to include `user_count` (number of members\nwho RSVP'd) on each event. Useful for surfacing engagement.\n","parameters":[{"name":"guildId","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"withUserCount","in":"query","required":false,"schema":{"type":"boolean"},"description":"Include user_count on each event."}],"responses":{"200":{"description":"List of scheduled events.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DiscordScheduledEvent"}}}}}}},"400":{"description":"Invalid params."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Discord account not found or not in this guild."},"502":{"description":"Bot lacks access to the guild's events."}}},"post":{"x-resource-group":"engagement","operationId":"createDiscordScheduledEvent","tags":["Discord"],"summary":"Create a Discord scheduled event","description":"Create a guild scheduled event. Three event types, selected via the\ndiscriminator on `entity.type`:\n\n  - `external`: off-platform (Zoom, in-person, livestream). Requires\n    both `location` and `endsAt`. Most common type for scheduler\n    integrations.\n  - `voice`: hosted in a Discord voice channel. Requires `channelId`.\n  - `stage`: hosted in a Discord stage channel. Requires `channelId`.\n\nBot needs MANAGE_EVENTS in the guild. Existing installs (pre-events\nPR) need a re-invite OR a server admin manually granting the\npermission. See route header for details.\n","parameters":[{"name":"guildId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","name","startsAt","entity"],"properties":{"accountId":{"type":"string"},"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":1000},"startsAt":{"type":"string","format":"date-time","description":"ISO 8601 start time. Must be in the future."},"entity":{"oneOf":[{"type":"object","required":["type","location","endsAt"],"properties":{"type":{"type":"string","enum":["external"]},"location":{"type":"string","minLength":1,"maxLength":100,"description":"Where the event takes place (e.g. \"Zoom link\", \"123 Main St\")"},"endsAt":{"type":"string","format":"date-time"}}},{"type":"object","required":["type","channelId"],"properties":{"type":{"type":"string","enum":["voice"]},"channelId":{"type":"string","description":"Voice channel snowflake."},"endsAt":{"type":"string","format":"date-time"}}},{"type":"object","required":["type","channelId"],"properties":{"type":{"type":"string","enum":["stage"]},"channelId":{"type":"string","description":"Stage channel snowflake."},"endsAt":{"type":"string","format":"date-time"}}}]},"imageDataUri":{"type":"string","pattern":"^data:image/(png|jpeg|gif);base64,","description":"Optional cover image as a base64 data URI."}}},"examples":{"external":{"value":{"accountId":"65a1b2c3d4e5f60718293a4b","name":"Weekly AMA","description":"Bring your questions about the roadmap.","startsAt":"2026-06-15T18:00:00Z","entity":{"type":"external","location":"https://zoom.us/j/123","endsAt":"2026-06-15T19:00:00Z"}}},"voice":{"value":{"accountId":"65a1b2c3d4e5f60718293a4b","name":"Game Night","startsAt":"2026-06-20T20:00:00Z","entity":{"type":"voice","channelId":"1234567890123456789"}}}}}}},"responses":{"200":{"description":"Event created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DiscordScheduledEvent"}}}}}},"400":{"description":"Validation error (missing required fields for the chosen entity type, malformed snowflake, past startsAt, etc.)."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Discord account not found."},"502":{"description":"Bot lacks MANAGE_EVENTS in the guild."}}}},"/v1/discord/guilds/{guildId}/events/{eventId}":{"get":{"x-resource-group":"engagement","operationId":"getDiscordScheduledEvent","tags":["Discord"],"summary":"Get a Discord scheduled event","parameters":[{"name":"guildId","in":"path","required":true,"schema":{"type":"string"}},{"name":"eventId","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Event.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DiscordScheduledEvent"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Event or Discord account not found."}}},"patch":{"x-resource-group":"engagement","operationId":"updateDiscordScheduledEvent","tags":["Discord"],"summary":"Update a Discord scheduled event","description":"Patch any subset of fields. Passing `status: 'cancelled'` is how you\ncancel an event. Discord doesn't have a dedicated cancel endpoint,\nit's a status transition.\n\nMost status transitions Discord enforces (you can't go SCHEDULED →\nCOMPLETED directly). The common consumer case is SCHEDULED → CANCELED.\n","parameters":[{"name":"guildId","in":"path","required":true,"schema":{"type":"string"}},{"name":"eventId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string"},"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":1000},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"location":{"type":"string","minLength":1,"maxLength":100,"description":"For external events."},"status":{"type":"string","enum":["scheduled","active","completed","cancelled"],"description":"Status transition. Most common: 'cancelled' to cancel an event."},"imageDataUri":{"type":"string","pattern":"^data:image/(png|jpeg|gif);base64,"}}},"example":{"accountId":"65a1b2c3d4e5f60718293a4b","status":"cancelled"}}}},"responses":{"200":{"description":"Event updated.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DiscordScheduledEvent"}}}}}},"400":{"description":"Validation error, no updatable fields beyond accountId provided, or Discord rejected the update (invalid status transition)."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Discord refused the update (bot permissions)."},"404":{"description":"Event or Discord account not found."},"502":{"description":"Discord was unreachable or returned an unclassified error."}}},"delete":{"x-resource-group":"engagement","operationId":"deleteDiscordScheduledEvent","tags":["Discord"],"summary":"Delete a Discord scheduled event","description":"Hard-delete an event. Use PATCH with `status: 'cancelled'` instead\nif you want the event preserved in the guild's history.\n","parameters":[{"name":"guildId","in":"path","required":true,"schema":{"type":"string"}},{"name":"eventId","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Event deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"deleted":{"type":"string","description":"The deleted event's snowflake."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Event or Discord account not found."},"502":{"description":"Bot lacks MANAGE_EVENTS in the guild."}}}},"/v1/queue/slots":{"get":{"x-resource-group":"publishing","operationId":"listQueueSlots","tags":["Queue"],"summary":"List schedules","description":"Returns queue schedules for a profile. Use all=true for all queues, or queueId for a specific one. Defaults to the default queue.","parameters":[{"name":"profileId","in":"query","required":true,"schema":{"type":"string"},"description":"Profile ID to get queues for"},{"name":"queueId","in":"query","required":false,"schema":{"type":"string"},"description":"Specific queue ID to retrieve (optional)"},{"name":"all","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]},"description":"Set to 'true' to list all queues for the profile"}],"responses":{"200":{"description":"Queue schedule(s) retrieved","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/QueueSlotsResponse"},{"type":"object","description":"All queues response (when all=true)","properties":{"queues":{"type":"array","items":{"$ref":"#/components/schemas/QueueSchedule"}},"count":{"type":"integer"}}}]},"examples":{"singleQueue":{"summary":"Single queue response","value":{"exists":true,"schedule":{"_id":"64f0a1b2c3d4e5f6a7b8c9d1","profileId":"64f0a1b2c3d4e5f6a7b8c9d0","name":"Morning Posts","timezone":"America/New_York","slots":[{"dayOfWeek":1,"time":"09:00"},{"dayOfWeek":3,"time":"09:00"},{"dayOfWeek":5,"time":"10:00"}],"active":true,"isDefault":true},"nextSlots":["2024-11-04T09:00:00-05:00","2024-11-06T09:00:00-05:00"]}},"allQueues":{"summary":"All queues response (all=true)","value":{"queues":[{"_id":"64f0a1b2c3d4e5f6a7b8c9d1","name":"Morning Posts","isDefault":true,"timezone":"America/New_York","slots":[{"dayOfWeek":1,"time":"09:00"}],"active":true},{"_id":"64f0a1b2c3d4e5f6a7b8c9d2","name":"Evening Content","isDefault":false,"timezone":"America/New_York","slots":[{"dayOfWeek":1,"time":"18:00"}],"active":true}],"count":2}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Profile not found"}}},"post":{"x-resource-group":"publishing","operationId":"createQueueSlot","tags":["Queue"],"summary":"Create schedule","description":"Create an additional queue for a profile. The first queue created becomes the default.\nSubsequent queues are non-default unless explicitly set.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","name","timezone","slots"],"properties":{"profileId":{"type":"string","description":"Profile ID"},"name":{"type":"string","description":"Queue name (e.g., Evening Posts)"},"timezone":{"type":"string","description":"IANA timezone"},"slots":{"type":"array","items":{"$ref":"#/components/schemas/QueueSlot"}},"active":{"type":"boolean","default":true}}},"example":{"profileId":"64f0a1b2c3d4e5f6a7b8c9d0","name":"Evening Posts","timezone":"America/New_York","slots":[{"dayOfWeek":1,"time":"18:00"},{"dayOfWeek":3,"time":"18:00"},{"dayOfWeek":5,"time":"18:00"}],"active":true}}}},"responses":{"201":{"description":"Queue created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"schedule":{"$ref":"#/components/schemas/QueueSchedule"},"nextSlots":{"type":"array","items":{"type":"string","format":"date-time"}}}}}}},"400":{"description":"Invalid request or validation error"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Profile not found"}}},"put":{"x-resource-group":"publishing","operationId":"updateQueueSlot","tags":["Queue"],"summary":"Update schedule","description":"Create a new queue or update an existing one. Without queueId, creates/updates the default queue. With queueId, updates a specific queue. With setAsDefault=true, makes this queue the default for the profile.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","timezone","slots"],"properties":{"profileId":{"type":"string"},"queueId":{"type":"string","description":"Queue ID to update (optional)"},"name":{"type":"string","description":"Queue name"},"timezone":{"type":"string"},"slots":{"type":"array","items":{"$ref":"#/components/schemas/QueueSlot"}},"active":{"type":"boolean","default":true},"setAsDefault":{"type":"boolean","description":"Make this queue the default"},"reshuffleExisting":{"type":"boolean","default":false,"description":"Whether to reschedule existing queued posts to match new slots"}}},"example":{"profileId":"64f0a1b2c3d4e5f6a7b8c9d0","queueId":"64f0a1b2c3d4e5f6a7b8c9d1","name":"Morning Posts","timezone":"America/New_York","slots":[{"dayOfWeek":1,"time":"09:00"},{"dayOfWeek":3,"time":"09:00"},{"dayOfWeek":5,"time":"10:00"}],"active":true,"setAsDefault":false}}}},"responses":{"200":{"description":"Queue schedule updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueueUpdateResponse"},"example":{"success":true,"schedule":{"_id":"64f0a1b2c3d4e5f6a7b8c9d1","profileId":"64f0a1b2c3d4e5f6a7b8c9d0","name":"Morning Posts","timezone":"America/New_York","slots":[{"dayOfWeek":1,"time":"09:00"},{"dayOfWeek":3,"time":"09:00"},{"dayOfWeek":5,"time":"10:00"}],"active":true,"isDefault":true},"nextSlots":["2024-11-04T09:00:00-05:00","2024-11-06T09:00:00-05:00"],"reshuffledCount":0}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Profile not found"}}},"delete":{"x-resource-group":"publishing","operationId":"deleteQueueSlot","tags":["Queue"],"summary":"Delete schedule","description":"Delete a queue from a profile. Pass queueId to delete a specific queue;\nomit it to delete all queues for the profile.\nIf deleting the default queue, another queue will be promoted to default.\n","parameters":[{"name":"profileId","in":"query","required":true,"schema":{"type":"string"}},{"name":"queueId","in":"query","required":false,"schema":{"type":"string"},"description":"Queue ID to delete. Omit to delete all queues for the profile"}],"responses":{"200":{"description":"Queue schedule deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueueDeleteResponse"},"example":{"success":true,"deleted":true}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Profile or queue not found"}}}},"/v1/queue/preview":{"get":{"x-resource-group":"publishing","operationId":"previewQueue","tags":["Queue"],"summary":"Preview upcoming slots","description":"Returns the next N upcoming queue slot times for a profile as ISO datetime strings.","parameters":[{"name":"profileId","in":"query","required":true,"schema":{"type":"string"}},{"name":"queueId","in":"query","schema":{"type":"string"},"description":"Filter by specific queue ID. Omit to use the default queue."},{"name":"count","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Queue slots preview","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueuePreviewResponse"},"example":{"profileId":"64f0a1b2c3d4e5f6a7b8c9d0","count":10,"slots":["2024-11-04T09:00:00-05:00","2024-11-04T14:00:00-05:00","2024-11-06T09:00:00-05:00","2024-11-08T10:00:00-05:00","2024-11-11T09:00:00-05:00","2024-11-11T14:00:00-05:00","2024-11-13T09:00:00-05:00","2024-11-15T10:00:00-05:00","2024-11-18T09:00:00-05:00","2024-11-18T14:00:00-05:00"]}}}},"400":{"description":"Invalid parameters"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Profile or queue schedule not found"}}}},"/v1/queue/next-slot":{"get":{"x-resource-group":"publishing","operationId":"getNextQueueSlot","tags":["Queue"],"summary":"Get next available slot","description":"Returns the next available queue slot for preview purposes. To create a queue post, use POST /v1/posts with queuedFromProfile instead of scheduledFor.","parameters":[{"name":"profileId","in":"query","required":true,"schema":{"type":"string"}},{"name":"queueId","in":"query","required":false,"schema":{"type":"string"},"description":"Specific queue ID (optional, defaults to profile's default queue)"}],"responses":{"200":{"description":"Next available slot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueueNextSlotResponse"},"example":{"profileId":"64f0a1b2c3d4e5f6a7b8c9d0","nextSlot":"2024-11-04T09:00:00-05:00","timezone":"America/New_York","queueId":"64f0a1b2c3d4e5f6a7b8c9d1","queueName":"Morning Posts"}}}},"400":{"description":"Invalid parameters or inactive queue"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Profile or queue schedule not found, or no available slots"}}}},"/v1/webhooks/settings":{"get":{"x-resource-group":"webhooks","operationId":"getWebhookSettings","tags":["Webhooks"],"summary":"List webhooks","description":"Retrieve all configured webhooks for the authenticated user. Supports up to 50 webhooks per user.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Webhooks retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}},"example":{"webhooks":[{"_id":"507f1f77bcf86cd799439011","name":"My Production Webhook","url":"https://example.com/webhook","events":["post.published","post.failed"],"isActive":true,"profileIds":[],"accountIds":[],"lastFiredAt":"2024-01-15T10:30:00Z","failureCount":0},{"_id":"507f1f77bcf86cd799439012","name":"Slack Notifications","url":"https://hooks.slack.com/services/xxx","events":["post.failed","account.disconnected"],"isActive":true,"failureCount":0}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"}}},"post":{"x-resource-group":"webhooks","operationId":"createWebhookSettings","tags":["Webhooks"],"summary":"Create webhook","description":"Create a new webhook configuration. Maximum 50 webhooks per user.\n\n`name`, `url` and `events` are required. `url` must be a valid URL and `events` must contain at least one event. Whitespace is trimmed from `url` before validation.\n\n### Auto-disable\n\nA webhook is auto-disabled only once the endpoint has had no successful delivery for 3 days AND either:\n\n- has reached 20 consecutive terminal failures (each one an event that exhausted the full retry ladder), or\n- has been failing continuously for 3 days.\n\nThe owner is emailed; re-enable it with `isActive: true`.\n\n### Restricted keys\n\nA restricted (zrk_) API key can only subscribe to events whose resource group the key holds. An event outside the key's groups is rejected with 403, so a restricted key can never create a subscription broader than itself.\n\n### Filtering what is delivered\n\n`disabledResourceGroups` restricts the subscription itself, independently of which key or session later reads it. Events in a disabled group are dropped before delivery to this endpoint, even if they are listed in `events`. This applies on live delivery and on every replay path (test fire, redelivery, dead-letter requeue).\n\nOmit it to receive everything in `events`, which is how existing subscriptions behave. A restricted key's own disabled groups are always unioned in.\n\n`profileIds` pins the subscription to a set of profiles and `accountIds` to a set of connected accounts. Only events attributable to one of the listed ids are delivered, and a subscription with both lists must match on both. Use them to send test accounts to a staging endpoint.\n\nIds outside your team are rejected with 404 (`profile_not_found`, `account_not_found`).\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","url","events"],"properties":{"name":{"type":"string","description":"Webhook name (1-50 characters)","minLength":1,"maxLength":50},"url":{"type":"string","format":"uri","description":"Webhook endpoint URL (must be a valid URL, whitespace trimmed)"},"secret":{"type":"string","description":"Secret key for HMAC-SHA256 signature verification"},"events":{"type":"array","minItems":1,"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.permissions_changed","account.ads.initial_sync_completed","account.ads.sync_failed","account.ads.sync_recovered","analytics.synced","post.tracking_completed","post.authenticity_changed","message.received","conversation.started","conversation.control_changed","call.received","call.ended","call.failed","call.permission_request","message.sent","message.edited","message.deleted","message.delivered","message.read","message.played","message.failed","reaction.received","referral.received","comment.received","review.new","review.updated","review.deleted","review.restored","lead.received","ad.status_changed","ad.created","ad.updated","campaign.created","campaign.updated","ad.review.approved","ad.review.rejected","ad.delivery_issue","campaign.budget.depleted","ad_account.status_changed","ad.video.processed","ad_rule.triggered","automation.check.completed","automation.action.applied","automation.action.failed","automation.action.unknown","automation.alert.opened","automation.alert.escalated","automation.alert.resolved","whatsapp.template.status_updated","whatsapp.template.category_updated","whatsapp.account.name_status_updated","whatsapp.account.quality_updated","whatsapp.account.status_updated","whatsapp.account.alert_received","whatsapp.contact.identity_changed","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","phone_number.stock_available","verification.approved","verification.failed","api.changelog.published","sms.registration.action_required","sms.registration.status_updated","branded_calling.identity.status_updated","branded_calling.identity.action_required","branded_calling.number.status_updated","rcs.agent.status_updated","commerce.product.created","commerce.product.updated","commerce.product.deleted","commerce.order.created","commerce.order.updated","commerce.order.refunded","contact.tag_added","contact.tag_removed","contact.field_changed","sequence.enrolled","sequence.exited","workflow.run.started","workflow.run.completed","workflow.run.failed","support.run.completed","support.run.failed","campaign_submission.received","campaign_submission.flagged","campaign_submission.pending_review","campaign_submission.approved","campaign_submission.rejected","creator_campaign.budget_exhausted","creator_campaign.closed","campaign_payout.payable","campaign_payout.settled","campaign_payout.failed","campaign_participant.joined","campaign_participant.suspended","campaign_participant.removed"]},"description":"Events to subscribe to (at least one required)"},"isActive":{"type":"boolean","default":true,"description":"Enable or disable webhook delivery. Defaults to `true` when omitted."},"customHeaders":{"type":"object","additionalProperties":{"type":"string"},"description":"Custom headers to include in webhook requests"},"disabledResourceGroups":{"type":"array","items":{"type":"string","enum":["publishing","engagement","messages","contacts","analytics","ads","telephony","accounts","billing","webhooks","commerce","creator_campaigns","money","calendar","files"]},"description":"Resource groups this subscription does not receive (opt-out denylist). Omit or send an empty array to receive every event in `events`.\n\n- Listing a group here drops its events before delivery and on every replay path.\n- Set at creation, it applies to everything this subscription ever receives.\n- Changed later via PUT, it applies to events emitted after the change, with a five-minute tail for events already queued (see that operation).\n- For a restricted (zrk_) key, that key's own disabled groups are unioned into whatever you send here, so a restricted key can never create a subscription wider than itself.\n"},"profileIds":{"type":"array","maxItems":50,"items":{"type":"string"},"description":"Profiles this subscription receives events for. Omit or send an empty array to receive every profile. Every id must be a profile in your team, otherwise the request fails with 404 `profile_not_found` and nothing is created. Typical use is routing the profile that holds test accounts to a staging endpoint."},"accountIds":{"type":"array","maxItems":50,"items":{"type":"string"},"description":"Connected accounts this subscription receives events for. Omit or send an empty array to receive every account. Every id must be an account in your team, otherwise the request fails with 404 `account_not_found` and nothing is created. Combine with `profileIds` to narrow further; both must match."}}},"examples":{"createWebhook":{"summary":"Create webhook with all events","value":{"name":"My Production Webhook","url":"https://example.com/webhook","secret":"your-secret-key","events":["post.scheduled","post.published","post.failed","post.partial","post.cancelled","post.recycled","account.connected","account.disconnected","account.ads.initial_sync_completed","message.received","message.sent","message.edited","message.deleted","message.delivered","message.read","message.failed","comment.received","review.new","review.updated","ad.status_changed"],"isActive":true}},"createWebhookWithoutMessages":{"summary":"Subscription that does not receive direct message payloads","value":{"name":"Publishing Webhook","url":"https://example.com/webhook","events":["post.published","post.failed","comment.received"],"disabledResourceGroups":["messages","contacts"],"isActive":true}},"createStagingWebhook":{"summary":"Subscription that only receives one profile's events","value":{"name":"Staging Webhook","url":"https://staging.example.com/webhook","events":["post.published","post.failed","message.received"],"profileIds":["66a1f0c2a4b9d3e8f1a2b3c4"],"isActive":true}}}}}},"responses":{"200":{"description":"Webhook created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"webhook":{"$ref":"#/components/schemas/Webhook"}}}}}},"400":{"description":"Validation error or maximum webhooks reached"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"},"404":{"description":"A profile in `profileIds` (`profile_not_found`) or an account in `accountIds` (`account_not_found`) is not in your team"}}},"put":{"x-resource-group":"webhooks","operationId":"updateWebhookSettings","tags":["Webhooks"],"summary":"Update webhook","description":"Update an existing webhook configuration. All fields except `webhookId` are optional; only provided fields will be updated.\n\n`webhookId` is the same name the other /v1/webhooks operations use (logs, redeliver, test). The deprecated `_id` is still accepted in its place.\n\n### Validation\n\nWhen provided:\n\n- `name` must be 1-50 characters.\n- `url` must be a valid URL. Whitespace is trimmed from `url` before validation.\n- `events` must contain at least one event.\n\n### Auto-disable\n\nWebhooks are auto-disabled only once the endpoint has had no successful delivery for 3 days AND either:\n\n- has reached 20 consecutive terminal failures (each one an event that exhausted the full retry ladder), or\n- has been failing continuously for 3 days.\n\nThe owner is emailed. Re-enable it with `isActive: true`.\n\n### Restricted keys\n\nA restricted (zrk_) API key can only set `events` to events whose resource group the key holds. An event outside the key's groups is rejected with 403. It also cannot widen an existing subscription past its own groups.\n\n### `disabledResourceGroups`\n\n`disabledResourceGroups` replaces the subscription's own denylist, which applies to delivery regardless of which key or session created it. Send an empty array to clear it.\n\nA restricted key's own disabled groups are unioned into the stored value on every update. So repointing a legacy unrestricted subscription with a restricted key also narrows it.\n\n### Denylist timing\n\nThe new denylist applies to every event emitted after the update.\n\nEvents already queued for delivery when the update landed were filtered against the previous denylist. They can still arrive at your endpoint for up to five minutes after they were enqueued, because the delivery worker trusts a five-minute enqueue-time snapshot before re-checking the subscription.\n\nRetries beyond that window, dead-letter replays, test fires, and redeliveries are all checked against the current denylist.\n\n### Allowlists\n\n`profileIds` and `accountIds` replace the subscription's allowlists; an empty array clears one. Ids outside your team are rejected with 404 (`profile_not_found`, `account_not_found`).\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"webhookId":{"type":"string","description":"Webhook ID to update. Required unless the deprecated `_id` is sent instead."},"_id":{"type":"string","deprecated":true,"description":"Alias of webhookId, kept for existing callers"},"name":{"type":"string","description":"Webhook name (1-50 characters). Must be non-empty if provided.","minLength":1,"maxLength":50},"url":{"type":"string","format":"uri","description":"Webhook endpoint URL (must be a valid URL, whitespace trimmed). Must be a valid URL if provided."},"secret":{"type":"string","description":"Secret key for HMAC-SHA256 signature verification"},"events":{"type":"array","minItems":1,"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.permissions_changed","account.ads.initial_sync_completed","account.ads.sync_failed","account.ads.sync_recovered","analytics.synced","post.tracking_completed","post.authenticity_changed","message.received","conversation.started","conversation.control_changed","call.received","call.ended","call.failed","call.permission_request","message.sent","message.edited","message.deleted","message.delivered","message.read","message.played","message.failed","reaction.received","referral.received","comment.received","review.new","review.updated","review.deleted","review.restored","lead.received","ad.status_changed","ad.created","ad.updated","campaign.created","campaign.updated","ad.review.approved","ad.review.rejected","ad.delivery_issue","campaign.budget.depleted","ad_account.status_changed","ad.video.processed","ad_rule.triggered","automation.check.completed","automation.action.applied","automation.action.failed","automation.action.unknown","automation.alert.opened","automation.alert.escalated","automation.alert.resolved","whatsapp.template.status_updated","whatsapp.template.category_updated","whatsapp.account.name_status_updated","whatsapp.account.quality_updated","whatsapp.account.status_updated","whatsapp.account.alert_received","whatsapp.contact.identity_changed","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","phone_number.stock_available","verification.approved","verification.failed","api.changelog.published","sms.registration.action_required","sms.registration.status_updated","branded_calling.identity.status_updated","branded_calling.identity.action_required","branded_calling.number.status_updated","rcs.agent.status_updated","commerce.product.created","commerce.product.updated","commerce.product.deleted","commerce.order.created","commerce.order.updated","commerce.order.refunded","contact.tag_added","contact.tag_removed","contact.field_changed","sequence.enrolled","sequence.exited","workflow.run.started","workflow.run.completed","workflow.run.failed","support.run.completed","support.run.failed","campaign_submission.received","campaign_submission.flagged","campaign_submission.pending_review","campaign_submission.approved","campaign_submission.rejected","creator_campaign.budget_exhausted","creator_campaign.closed","campaign_payout.payable","campaign_payout.settled","campaign_payout.failed","campaign_participant.joined","campaign_participant.suspended","campaign_participant.removed"]},"description":"Events to subscribe to. Must contain at least one event if provided."},"isActive":{"type":"boolean","description":"Enable or disable webhook delivery"},"customHeaders":{"type":"object","additionalProperties":{"type":"string"},"description":"Custom headers to include in webhook requests"},"disabledResourceGroups":{"type":"array","items":{"type":"string","enum":["publishing","engagement","messages","contacts","analytics","ads","telephony","accounts","billing","webhooks","commerce","creator_campaigns","money","calendar","files"]},"description":"Replaces the subscription's denylist.\n\n- Send an empty array to clear it and receive every event in `events` again.\n- Omit the field to leave the current denylist untouched.\n- Applies to events emitted after the update; already-queued events can still deliver for up to five minutes after they were enqueued.\n- With a restricted (zrk_) key, that key's own disabled groups are unioned back in either way, so it can neither clear nor widen a subscription past its own groups.\n"},"profileIds":{"type":"array","maxItems":50,"items":{"type":"string"},"description":"Replaces the subscription's profile allowlist. Applies to events emitted after the update.\n\n- Empty array: receive every profile again.\n- Omitted: the current list is left untouched.\n- Every id must be a profile in your team, otherwise the request fails with 404 `profile_not_found` and nothing changes.\n\nSending the stored list back unchanged is accepted without re-validation, so an endpoint stays editable after a listed profile is deleted.\n"},"accountIds":{"type":"array","maxItems":50,"items":{"type":"string"},"description":"Replaces the subscription's account allowlist.\n\n- Send an empty array to receive every account again.\n- Omit the field to leave the current list untouched.\n- Every id must be an account in your team, otherwise the request fails with 404 `account_not_found` and nothing changes.\n- Sending the stored list back unchanged is accepted without re-validation.\n"}}},"examples":{"updateWebhook":{"summary":"Update webhook URL and events","value":{"_id":"507f1f77bcf86cd799439011","url":"https://new-example.com/webhook","events":["post.published","post.failed"]}},"toggleWebhook":{"summary":"Enable/disable webhook","value":{"_id":"507f1f77bcf86cd799439011","isActive":false}}}}}},"responses":{"200":{"description":"Webhook updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"webhook":{"$ref":"#/components/schemas/Webhook"}}}}}},"400":{"description":"Validation error or missing webhook ID"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"},"404":{"description":"Webhook not found, or a profile in `profileIds` (`profile_not_found`) / an account in `accountIds` (`account_not_found`) is not in your team"}}},"delete":{"x-resource-group":"webhooks","operationId":"deleteWebhookSettings","tags":["Webhooks"],"summary":"Delete webhook","description":"Permanently delete a webhook configuration.","security":[{"bearerAuth":[]}],"parameters":[{"name":"webhookId","in":"query","required":false,"description":"Webhook ID to delete, the same name the other /v1/webhooks operations use (logs, redeliver, test). Required unless the deprecated `id` is sent instead.","schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"}},{"name":"id","in":"query","required":false,"deprecated":true,"description":"Alias of webhookId, kept for existing callers","schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"}}],"responses":{"200":{"description":"Webhook deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"x-summary":"The webhookId is missing or invalid, or the request has a query parameter this endpoint does not know: fix the request.","description":"webhookId missing or not a valid ID, or a query parameter this endpoint does not know (the message lists the accepted ones; nothing is silently ignored)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"}}}},"/v1/webhooks/logs":{"get":{"x-resource-group":"webhooks","operationId":"getWebhookLogs","tags":["Webhooks"],"summary":"List webhook delivery logs","description":"Retrieve recorded webhook delivery attempts for the authenticated user, most recent first.\n\nLogs are retained for 30 days. Supports filtering by status, event type, webhook ID, and event ID, plus offset-based pagination.\n\n### Restricted keys\n\nFor a restricted (zrk_) API key:\n\n- Rows for events outside the key's resource groups are omitted (`pagination.total` may over-count).\n- An `event` filter naming such an event is rejected with 403.\n\n### Denylisted events\n\nEvents blocked by a subscription's own `disabledResourceGroups` are dropped before delivery, so they produce no log rows for anyone.\n\nThe exception is the five-minute tail after a denylist change, where an already-queued event can still be delivered and logged.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of logs to return","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"skip","in":"query","description":"Number of logs to skip (offset-based pagination)","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}},{"name":"status","in":"query","description":"Filter by delivery outcome","schema":{"type":"string","enum":["success","failed"]}},{"name":"event","in":"query","description":"Filter by event type (e.g. post.published)","schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"webhookId","in":"query","description":"Filter by webhook configuration ID","schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"eventId","in":"query","description":"Filter by stable webhook event ID","schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"Webhook logs retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"logs":{"type":"array","items":{"$ref":"#/components/schemas/WebhookLog"}},"pagination":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of matching logs"},"limit":{"type":"integer","description":"Maximum number of logs returned per page"},"skip":{"type":"integer","description":"Number of logs skipped"},"pages":{"type":"integer","description":"Total number of pages"},"hasMore":{"type":"boolean","description":"Whether more logs are available beyond this page"}}}}}}}},"400":{"description":"Invalid query parameter"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"}}}},"/v1/webhooks/logs/redeliver":{"post":{"x-resource-group":"webhooks","operationId":"redeliverWebhookEvent","tags":["Webhooks"],"summary":"Redeliver a webhook event","description":"Replay a past delivery: the original payload is re-sent, byte for byte, to the\nsubscription's current URL. The original event ID is preserved so your endpoint can\ndedupe, and the replay is recorded as a fresh attempt, so it shows up in\n`GET /v1/webhooks/logs` next to the delivery it replays.\n\nBoth `webhookId` and `eventId` come from a row of `GET /v1/webhooks/logs`. Because\nthe stored payload is replayed as-is, a redelivery reflects the event as it was\nemitted, not the current state of the resource.\n\nOnly deliveries inside the 30-day log retention window can be replayed; past that\nthe payload is gone and the request fails with a 422. Replays run the same\nresource-group checks as live delivery, against both the key's groups and the\nsubscription's `disabledResourceGroups`.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["webhookId","eventId"],"properties":{"webhookId":{"type":"string","minLength":1,"description":"ID of the webhook subscription that delivered the event"},"eventId":{"type":"string","minLength":1,"description":"Stable event ID of the delivery to replay"}}},"example":{"webhookId":"507f1f77bcf86cd799439011","eventId":"evt_9f2c1b7a4d8e"}}}},"responses":{"200":{"description":"Event re-delivered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"example":{"success":true,"message":"Webhook re-delivered"}}}},"400":{"description":"webhookId or eventId missing or empty, or the subscription has no URL configured"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"},"404":{"description":"Webhook subscription not found"},"422":{"x-summary":"The original payload cannot be replayed because no delivery matches within 30 days, or the stored payload is truncated or invalid.","description":"Original payload not replayable: no delivery matches this event inside the 30-day retention window, or the stored payload is truncated or not valid JSON"},"502":{"x-summary":"The redelivery was attempted but your endpoint errored again: fix your endpoint, since the attempt is still logged.","description":"Re-delivery was attempted but your endpoint errored again. The attempt is still\nlogged; `message` describes the failure.\n","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}}}}},"/v1/webhooks/test":{"post":{"x-resource-group":"webhooks","operationId":"testWebhook","tags":["Webhooks"],"summary":"Send test webhook","description":"Send a test webhook to verify your endpoint is configured correctly. The test payload includes event: \"webhook.test\" to distinguish it from real events.\n\n### Sample payload for a specific event\n\nPass `event` to receive a sample payload of that event instead. This exercises the handler for an event that only fires on a real outage or lifecycle change (e.g. `account.ads.sync_failed`).\n\n- The sample has the exact shape documented for the event under Webhook Events.\n- It is delivered like a real one, with the same `X-Zernio-Event`, `X-Zernio-Event-Id` and `X-Zernio-Signature` headers.\n- It carries a top-level `test: true` and placeholder ids, never your data.\n- The delivery shows up in the webhook logs with `test: true`.\n\nThe webhook does not have to be subscribed to the event. But a webhook that lists the event's resource group in its `disabledResourceGroups` answers 403, as does an API key with that group disabled.\n\n### Resource group checks\n\n`webhook.test` belongs to the `webhooks` resource group. A test fire is rejected with 403 (not a reported delivery failure) when:\n\n- the key has that group disabled;\n- the subscription lists `webhooks` in its own `disabledResourceGroups`.\n\nReplays of real events (redelivery, dead-letter requeue) run the same checks as live delivery, against both the key's groups and the subscription's.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["webhookId"],"properties":{"webhookId":{"type":"string","description":"ID of the webhook to test"},"event":{"type":"string","description":"Send a sample payload of this event instead of `webhook.test`. The sample is marked with `test: true`.","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.permissions_changed","account.ads.initial_sync_completed","account.ads.sync_failed","account.ads.sync_recovered","account.rate_limited","calendar.event.created","calendar.event.updated","calendar.event.deleted","file.created","file.updated","file.deleted","file.picked","contact.updated","contact.deleted","analytics.synced","post.tracking_completed","post.authenticity_changed","message.received","message.sent","message.edited","message.deleted","message.delivered","message.read","message.played","message.failed","reaction.received","referral.received","conversation.started","conversation.control_changed","contact.tag_added","contact.tag_removed","contact.field_changed","sequence.enrolled","sequence.exited","workflow.run.started","workflow.run.completed","workflow.run.failed","support.run.completed","support.run.failed","campaign_submission.received","campaign_submission.flagged","campaign_submission.pending_review","campaign_submission.approved","campaign_submission.rejected","creator_campaign.budget_exhausted","creator_campaign.closed","campaign_payout.payable","campaign_payout.settled","campaign_payout.failed","campaign_participant.joined","campaign_participant.suspended","campaign_participant.removed","call.received","call.ended","call.failed","call.permission_request","comment.received","review.new","review.updated","review.deleted","review.restored","ad.status_changed","ad.created","ad.updated","campaign.created","campaign.updated","ad.review.approved","ad.review.rejected","ad.delivery_issue","campaign.budget.depleted","ad_account.status_changed","ad.video.processed","ad_rule.triggered","automation.check.completed","automation.action.applied","automation.action.failed","automation.action.unknown","automation.alert.opened","automation.alert.escalated","automation.alert.resolved","lead.received","whatsapp.template.status_updated","whatsapp.template.category_updated","whatsapp.account.name_status_updated","whatsapp.account.quality_updated","whatsapp.account.status_updated","whatsapp.account.alert_received","whatsapp.contact.identity_changed","whatsapp.number.activated","whatsapp.number.declined","whatsapp.number.action_required","whatsapp.automatic_event","whatsapp.number.verification_required","whatsapp.number.suspended","whatsapp.number.reactivated","whatsapp.number.released","whatsapp.number.kyc_submitted","phone_number.stock_available","sms.registration.action_required","sms.registration.status_updated","branded_calling.identity.status_updated","branded_calling.identity.action_required","branded_calling.number.status_updated","rcs.agent.status_updated","verification.approved","verification.failed","commerce.product.created","commerce.product.updated","commerce.product.deleted","commerce.order.created","commerce.order.updated","commerce.order.refunded","api.changelog.published"]}}},"examples":{"generic":{"summary":"Generic webhook.test payload","value":{"webhookId":"507f1f77bcf86cd799439011"}},"sampleEvent":{"summary":"Sample payload of a specific event","value":{"webhookId":"507f1f77bcf86cd799439011","event":"account.ads.sync_failed"}}}}}},"responses":{"200":{"description":"Test webhook sent successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"example":{"success":true,"message":"Test webhook sent successfully"}}}},"400":{"description":"Webhook ID missing, or `event` is not one of the listed events (omit `event` to send `webhook.test`)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"},"404":{"description":"Webhook not found"},"500":{"description":"Test webhook failed to deliver","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"example":{"success":false,"message":"Test webhook failed"}}}}}}},"/v1/logs":{"get":{"x-resource-group":"publishing","operationId":"listLogs","tags":["Logs"],"summary":"List activity logs","description":"Unified logs endpoint. Returns logs for publishing, connections, webhooks, and messaging.\nFilter by type, platform, status, and time range. Logs are retained for 90 days.\nLegacy query aliases remain accepted: `account_id` for `accountId`, `request_id` for `requestId`,\n`status_code` for `statusCode`, `api_key_id` for `apiKeyId`, and `include_read_receipts` for `includeReadReceipts`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"type","in":"query","description":"Log category to query. Use `all` for the unified view across every category,\nor `api_request` for your API request logs (method, path, status, latency).\n","schema":{"type":"string","enum":["all","publishing","connections","webhooks","messaging","workflow_event","api_request"],"default":"publishing"}},{"name":"status","in":"query","description":"Filter by status","schema":{"type":"string","enum":["success","failed","pending","skipped","all"]}},{"name":"platform","in":"query","description":"Filter by platform","schema":{"type":"string","enum":["tiktok","instagram","whatsapp","facebook","youtube","linkedin","twitter","threads","pinterest","reddit","bluesky","googlebusiness","telegram","snapchat","all"]}},{"name":"action","in":"query","description":"Filter by action (e.g., post.published, message.sent, message.media_download_failed, account.connected, webhook.delivered)","schema":{"type":"string"}},{"name":"search","in":"query","description":"Free-text search across log fields","schema":{"type":"string"}},{"name":"days","in":"query","description":"Number of days to look back (max 90)","schema":{"type":"integer","minimum":1,"maximum":90,"default":90}},{"name":"limit","in":"query","description":"Maximum number of logs to return (max 100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"skip","in":"query","description":"Number of logs to skip (for pagination)","schema":{"type":"integer","minimum":0,"default":0}},{"name":"accountId","in":"query","description":"Filter by connected account ID","schema":{"type":"string"}},{"name":"event","in":"query","description":"Filter webhook logs by event (e.g. post.published, message.received)","schema":{"type":"string"}},{"name":"requestId","in":"query","description":"Correlation ID. Returns every log spawned by a single API request","schema":{"type":"string"}},{"name":"from","in":"query","description":"Precise start instant (ISO 8601); narrows within the day range","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Precise end instant (ISO 8601)","schema":{"type":"string","format":"date-time"}},{"name":"statusCode","in":"query","description":"Filter by exact HTTP status code (api_request logs)","schema":{"type":"integer"}},{"name":"apiKeyId","in":"query","description":"Filter by the API key that made the request (api_request logs)","schema":{"type":"string"}},{"name":"profileId","in":"query","description":"Filter by profile: every log type carries the profile it belongs to, and an API request log carries the profileId the call named","schema":{"type":"string"}},{"name":"includeReadReceipts","in":"query","description":"Include message.read / message.delivered events (hidden by default for messaging logs)","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Logs retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"logs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Log category (publishing, connections, webhooks, messaging)"},"action":{"type":"string","description":"Specific action (post.published, message.sent, account.connected, etc.)"},"user_id":{"type":"string"},"platform":{"type":"string"},"account_id":{"type":"string"},"profile_id":{"type":"string","description":"The profile the entry belongs to; on API request logs, the profileId the call named in its query or body"},"operation_id":{"type":"string","description":"API request logs only: the operationId of the public operation the request hit (e.g. createPost), absent for routes outside this spec"},"status":{"type":"string","enum":["success","failed","pending","skipped"]},"status_code":{"type":"integer"},"error_message":{"type":"string"},"error_code":{"type":"string"},"duration_ms":{"type":"integer"},"endpoint":{"type":"string","description":"The API endpoint that triggered this log"},"request_body":{"type":"string","description":"Request JSON (truncated to 5KB)"},"response_body":{"type":"string","description":"Response JSON (truncated to 10KB)"},"created_at":{"type":"string","format":"date-time"},"metadata":{"type":"string","description":"Additional context as JSON string"},"request_id":{"type":"string","description":"Correlation ID linking every log from one API request (api_request logs)"},"api_key_id":{"type":"string","description":"The API key that made the request (api_request logs)"},"method":{"type":"string","description":"HTTP method (api_request logs)"},"path":{"type":"string","description":"Request path (api_request logs)"},"ip_address":{"type":"string","description":"Client IP address (api_request logs)"},"user_agent":{"type":"string","description":"Client user-agent (api_request logs)"}}}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"skip":{"type":"integer"},"pages":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}}}},"400":{"x-summary":"A filter value is invalid: fix it, and note that unknown parameters are ignored on this list but rejected by related routes.","description":"Invalid filter value. Unknown parameters are ignored on this list; the histogram, facets and export routes reject them."},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/email/threads":{"get":{"x-resource-group":"messages","operationId":"listEmailThreads","tags":["Email"],"summary":"List email threads","description":"Threads of a connected Google or Microsoft mailbox, newest first. Every filter that the provider cannot apply server-side is applied to the fetched page instead and named in `meta.filteredClientSide`, so a filtered page can hold fewer than `limit` items while `pagination.hasMore` stays true.\n\nOn Google, folders are Gmail labels: `folder` takes a well-known name or a label id, `archive` means mail carrying none of the inbox, trash or spam labels, and `sortOrder=asc` reverses the fetched page (Gmail lists newest first only).\n\nThe account must have been connected with `scopes=email` (412 `account_scope_missing` otherwise).\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/EmailAccountId"},{"name":"folder","in":"query","schema":{"type":"string"},"description":"Well-known folder (`inbox`, `sent`, `drafts`, `trash`, `spam`, `archive`) or a provider folder id from `GET /v1/email/folders`. Default inbox."},{"name":"unread","in":"query","schema":{"type":"boolean"}},{"name":"starred","in":"query","schema":{"type":"boolean"}},{"name":"hasAttachment","in":"query","schema":{"type":"boolean"}},{"name":"subject","in":"query","schema":{"type":"string"},"description":"Substring match on the subject."},{"name":"from","in":"query","schema":{"type":"string"},"description":"Sender address."},{"name":"to","in":"query","schema":{"type":"string"},"description":"A recipient address."},{"name":"cc","in":"query","schema":{"type":"string"}},{"name":"bcc","in":"query","schema":{"type":"string"},"description":"Applied client-side on Microsoft."},{"name":"anyEmail","in":"query","schema":{"type":"string"},"description":"Matches from, to, cc or bcc. Applied client-side on Microsoft."},{"name":"after","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"before","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"searchQueryNative","in":"query","schema":{"type":"string","maxLength":500},"description":"The provider's own search syntax (Gmail search operators, Microsoft KQL). On Microsoft it cannot be combined with other filters or server-side ordering; those are applied to the page."},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Threads","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailThread"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"},"meta":{"$ref":"#/components/schemas/EmailListMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/email/threads/{threadId}":{"get":{"x-resource-group":"messages","operationId":"getEmailThread","tags":["Email"],"summary":"Get an email thread with its messages","security":[{"bearerAuth":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/EmailAccountId"}],"responses":{"200":{"description":"The thread and every message in it, oldest first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/EmailThread"},{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/EmailMessage"}}}}]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}},"patch":{"x-resource-group":"messages","operationId":"updateEmailThread","tags":["Email"],"summary":"Update every message in a thread","description":"Applies `unread`, `starred` or a `folder` move to each message of the thread.","security":[{"bearerAuth":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMessagePatch"}}}},"responses":{"200":{"description":"The updated thread","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmailThread"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}}},"/v1/email/messages":{"get":{"x-resource-group":"messages","operationId":"listEmailMessages","tags":["Email"],"summary":"List email messages","description":"Same filters and envelope as `GET /v1/email/threads`, one row per message. Bodies are omitted; fetch a message to read `text` and `html`.\n\n### On Google\n\n- List rows also omit `attachments` (Gmail's metadata pages carry headers only); `hasAttachment=true` still filters server-side.\n- `sortOrder=asc` reverses the fetched page.\n- `archive` means mail without the inbox, trash or spam labels.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/EmailAccountId"},{"name":"folder","in":"query","schema":{"type":"string"}},{"name":"unread","in":"query","schema":{"type":"boolean"}},{"name":"starred","in":"query","schema":{"type":"boolean"}},{"name":"hasAttachment","in":"query","schema":{"type":"boolean"}},{"name":"subject","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string"}},{"name":"to","in":"query","schema":{"type":"string"}},{"name":"cc","in":"query","schema":{"type":"string"}},{"name":"bcc","in":"query","schema":{"type":"string"}},{"name":"anyEmail","in":"query","schema":{"type":"string"}},{"name":"after","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"before","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"searchQueryNative","in":"query","schema":{"type":"string","maxLength":500}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Messages","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailMessage"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"},"meta":{"$ref":"#/components/schemas/EmailListMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"x-resource-group":"messages","operationId":"sendEmailMessage","tags":["Email"],"summary":"Send an email","description":"Sends from the connected mailbox and returns the stored sent copy.\n\nThe message is mirrored into the inbox (`message.sent` fires once) and counted against the mailbox's daily cap. The cap is reported in the `X-Zernio-Send-Limit`, `X-Zernio-Send-Remaining` and `X-Zernio-Send-Reset` response headers.\n\n### Sending limits\n\nThese mailboxes are for one-to-one mail, not bulk sends. Protection on every mailbox:\n\n- Daily cap: Microsoft 1,000; Google Workspace 500; Gmail consumer 200. Reaching it answers 429 `email_send_cap_reached` with `details.cap`.\n- The same body reaching more than 50 distinct recipients within an hour pauses the mailbox with an escalating cooldown (429 `rate_limited`, `account.rate_limited` webhook).\n\n### Other errors\n\n- 402: Gmail sends need a payment method on the workspace. Reading, calendar and files do not.\n- 400: `scheduledFor` and `holdAsDraft` are reserved and currently rejected.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEmailRequest"}}}},"responses":{"201":{"description":"The sent message","headers":{"X-Zernio-Send-Limit":{"schema":{"type":"integer"},"description":"Today's cap for this mailbox."},"X-Zernio-Send-Remaining":{"schema":{"type":"integer"}},"X-Zernio-Send-Reset":{"schema":{"type":"string","format":"date-time"},"description":"When the daily window resets (midnight UTC)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmailMessage"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"},"429":{"$ref":"#/components/responses/EmailSendRefused"}}}},"/v1/email/messages/{messageId}":{"get":{"x-resource-group":"messages","operationId":"getEmailMessage","tags":["Email"],"summary":"Get an email message","security":[{"bearerAuth":[]}],"parameters":[{"name":"messageId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/EmailAccountId"},{"name":"includeHeaders","in":"query","schema":{"type":"boolean","default":false},"description":"Include the raw internet headers under `headers`."},{"name":"raw","in":"query","schema":{"type":"boolean","default":false},"description":"Include the MIME source under `raw`."}],"responses":{"200":{"description":"The message with its bodies","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmailMessage"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}},"patch":{"x-resource-group":"messages","operationId":"updateEmailMessage","tags":["Email"],"summary":"Mark read or starred, or move a message","description":"`folder` moves the message. On Google a move swaps the inbox, trash and spam labels and keeps every other label; `archive` removes the inbox label.","security":[{"bearerAuth":[]}],"parameters":[{"name":"messageId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMessagePatch"}}}},"responses":{"200":{"x-summary":"The message was updated and returned: after a move on Microsoft the message id changes, so read the new one from `data.id`.","description":"The updated message. A move on Microsoft changes the message id; read it from `data.id`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmailMessage"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}},"delete":{"x-resource-group":"messages","operationId":"trashEmailMessage","tags":["Email"],"summary":"Move a message to trash","security":[{"bearerAuth":[]}],"parameters":[{"name":"messageId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/EmailAccountId"}],"responses":{"200":{"description":"Trashed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"trashed":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}}},"/v1/email/messages/{messageId}/reply":{"post":{"x-resource-group":"messages","operationId":"replyEmailMessage","tags":["Email"],"summary":"Reply to a message","description":"Replies inside the provider's thread: the provider builds the quoted original and threading headers, your `html` or `text` goes above the quote. `to`, `cc`, `bcc`, `replyTo`, `subject`, `headers` and `attachments` are honoured; `scheduledFor` and `holdAsDraft` are rejected like on send. Same protection, caps and headers as sending.","security":[{"bearerAuth":[]}],"parameters":[{"name":"messageId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SendEmailRequest"},{"type":"object","properties":{"mode":{"type":"string","enum":["reply","replyAll"],"default":"reply"},"subject":{"type":"string","maxLength":998,"description":"Optional on replies; the provider keeps the thread subject."}}}]}}}},"responses":{"201":{"description":"The sent reply","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmailMessage"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"},"429":{"$ref":"#/components/responses/EmailSendRefused"}}}},"/v1/email/folders":{"get":{"x-resource-group":"messages","operationId":"listEmailFolders","tags":["Email"],"summary":"List mailbox folders","description":"On Google, folders are Gmail labels (system labels carry `wellKnown`; `unreadCount` and `totalCount` are present only where Gmail reports them). There is no archive folder on Google; archived mail is listed with `folder=archive`.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/EmailAccountId"}],"responses":{"200":{"description":"Folders, with `wellKnown` set on the provider's system folders","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailFolder"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}}},"/v1/email/attachments/{attachmentId}":{"get":{"x-resource-group":"messages","operationId":"downloadEmailAttachment","tags":["Email"],"summary":"Download an attachment","description":"Streams the attachment bytes with its `Content-Type` and a `Content-Disposition` carrying the filename.","security":[{"bearerAuth":[]}],"parameters":[{"name":"attachmentId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/EmailAccountId"},{"name":"messageId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The attachment bytes","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}}},"/v1/calendar/calendars":{"get":{"x-resource-group":"calendar","operationId":"listCalendars","tags":["Calendar"],"summary":"List calendars","description":"The account must have been connected with `scopes=calendar` (412 `account_scope_missing` otherwise).","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/EmailAccountId"}],"responses":{"200":{"description":"Calendars","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Calendar"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}}},"/v1/calendar/events":{"get":{"x-resource-group":"calendar","operationId":"listCalendarEvents","tags":["Calendar"],"summary":"List events in a window","description":"Recurring series are expanded into their occurrences inside the window by default (`expandRecurring=false` lists the masters instead). `title` and `location` are substring matches applied to the fetched page.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/EmailAccountId"},{"name":"calendarId","in":"query","schema":{"type":"string"},"description":"Defaults to the primary calendar."},{"name":"from","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"title","in":"query","schema":{"type":"string"}},{"name":"location","in":"query","schema":{"type":"string"}},{"name":"showCancelled","in":"query","schema":{"type":"boolean","default":false}},{"name":"expandRecurring","in":"query","schema":{"type":"boolean","default":true}},{"name":"icalUid","in":"query","schema":{"type":"string"}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"asc"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"timezone","in":"query","schema":{"type":"string"},"description":"IANA zone the `start` and `end` offsets are rendered in. Default UTC."}],"responses":{"200":{"description":"Events","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CalendarEvent"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"x-resource-group":"calendar","operationId":"createCalendarEvent","tags":["Calendar"],"summary":"Create an event","description":"Creates a calendar event. Conferencing and recurrence behave differently on Microsoft and Google accounts.\n\n### Microsoft accounts\n\n- `conferencing: teams` adds a Teams meeting. The created event comes back with `conferencing: null` when the tenant has no Teams (the EEA Business Basic SKUs ship without it).\n- `google_meet` is rejected with 400 (`param: conferencing`).\n\n### Google accounts\n\n- `conferencing: google_meet` adds a Meet link.\n- `teams` is rejected with 400.\n- `recurrence` accepts any RRULE Google Calendar supports.\n\n### Recurrence\n\n`recurrence` takes one RRULE line with FREQ, INTERVAL, COUNT, UNTIL, BYDAY and BYSETPOS. Other parts are rejected with 400 (`param: recurrence`).\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCalendarEventRequest"}}}},"responses":{"201":{"description":"The created event","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CalendarEvent"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}}},"/v1/calendar/events/{eventId}":{"get":{"x-resource-group":"calendar","operationId":"getCalendarEvent","tags":["Calendar"],"summary":"Get an event","security":[{"bearerAuth":[]}],"parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/EmailAccountId"},{"name":"calendarId","in":"query","schema":{"type":"string"},"description":"The calendar holding the event (an id from GET /v1/calendar/calendars). Defaults to the primary calendar."},{"name":"timezone","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The event","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CalendarEvent"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}},"patch":{"x-resource-group":"calendar","operationId":"updateCalendarEvent","tags":["Calendar"],"summary":"Update an event","security":[{"bearerAuth":[]}],"parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string"},"calendarId":{"type":"string","description":"The calendar holding the event (an id from GET /v1/calendar/calendars). Defaults to the primary calendar."}}},{"$ref":"#/components/schemas/CalendarEventFields"}]}}}},"responses":{"200":{"description":"The updated event","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CalendarEvent"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}},"delete":{"x-resource-group":"calendar","operationId":"deleteCalendarEvent","tags":["Calendar"],"summary":"Delete an event","security":[{"bearerAuth":[]}],"parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/EmailAccountId"},{"name":"calendarId","in":"query","schema":{"type":"string"},"description":"The calendar holding the event (an id from GET /v1/calendar/calendars). Defaults to the primary calendar."}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}}},"/v1/calendar/events/{eventId}/rsvp":{"post":{"x-resource-group":"calendar","operationId":"rsvpCalendarEvent","tags":["Calendar"],"summary":"Respond to an invitation","description":"Accepts, declines or tentatively accepts on behalf of the mailbox and notifies the organizer.","security":[{"bearerAuth":[]}],"parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","status"],"properties":{"accountId":{"type":"string"},"calendarId":{"type":"string","description":"The calendar holding the event (an id from GET /v1/calendar/calendars). Defaults to the primary calendar."},"status":{"type":"string","enum":["accepted","declined","tentative"]},"comment":{"type":"string","maxLength":1000}}}}}},"responses":{"200":{"description":"The event after the response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CalendarEvent"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}}},"/v1/calendar/free-busy":{"post":{"x-resource-group":"calendar","operationId":"calendarFreeBusy","tags":["Calendar"],"summary":"Busy blocks for one or more accounts","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountIds","from","to"],"properties":{"accountIds":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string"}},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"One entry per account, busy blocks in UTC","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string"},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"busy":{"type":"array","items":{"$ref":"#/components/schemas/BusyBlock"}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}}},"/v1/calendar/availability":{"post":{"x-resource-group":"calendar","operationId":"calendarAvailability","tags":["Calendar"],"summary":"Find meeting slots across accounts","description":"Slots of `durationMinutes` every `intervalMinutes` between `from` and `to` that are free for every participant (`collective`) or for at least one (`max_availability`). Buffers pad the participants' existing meetings. Open hours are evaluated in each participant's own timezone; `defaultOpenHours` applies to participants without their own.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["participants","from","to","durationMinutes"],"properties":{"participants":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string"},"openHours":{"$ref":"#/components/schemas/OpenHours"}}}},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"durationMinutes":{"type":"integer","minimum":5,"maximum":480},"intervalMinutes":{"type":"integer","minimum":5,"maximum":240,"default":30},"roundTo":{"type":"integer","minimum":5,"maximum":60,"description":"Rounds the first candidate slot up to this many minutes."},"buffer":{"type":"object","properties":{"before":{"type":"integer","minimum":0,"maximum":240,"default":0},"after":{"type":"integer","minimum":0,"maximum":240,"default":0}}},"defaultOpenHours":{"$ref":"#/components/schemas/OpenHours"},"method":{"type":"string","enum":["collective","max_availability"],"default":"collective"}}}}}},"responses":{"200":{"description":"Candidate slots","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"timeSlots":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"accountIds":{"type":"array","items":{"type":"string"},"description":"The participants free in this slot."}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}}},"/v1/files":{"get":{"x-resource-group":"files","operationId":"listFiles","tags":["Files"],"summary":"List files in a folder or search the drive","description":"Lists the children of `folderId` (the root by default), folders first.\n\nWith `q` and no `folderId` the whole drive is searched by name (on Google, every drive the app can see, shared drives included).\n\n- The account must have been connected with `scopes=files` (412 `account_scope_missing` otherwise).\n- Cursors are opaque and provider-issued.\n- Google Drive returns only files Zernio created or the user picked (see the Files tag): an unpicked folder lists empty.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/EmailAccountId"},{"name":"folderId","in":"query","schema":{"type":"string"},"description":"Provider folder id; omit for the root."},{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Name search."},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Files","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FileItem"}},"pagination":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}},"post":{"x-resource-group":"files","operationId":"uploadFile","tags":["Files"],"summary":"Upload a file","description":"Either `multipart/form-data` with the file under `file` plus `accountId`, `name` (defaults to the file name) and `parentId`, or JSON with a public `url` the file is fetched from (100 MB cap). Large files go through the provider's resumable upload.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","name","contentType","url"],"properties":{"accountId":{"type":"string"},"name":{"type":"string","maxLength":255},"contentType":{"type":"string","example":"image/png"},"parentId":{"type":"string","description":"Target folder; the root when omitted."},"url":{"type":"string","format":"uri"},"convertTo":{"type":"string","enum":["application/vnd.google-apps.document","application/vnd.google-apps.spreadsheet","application/vnd.google-apps.presentation"],"description":"Google Drive only: import the bytes as a Docs, Sheets or Slides file (a text or Office file becomes an editable document). OneDrive answers 400."}}}},"multipart/form-data":{"schema":{"type":"object","required":["accountId","file"],"properties":{"accountId":{"type":"string"},"file":{"type":"string","format":"binary"},"name":{"type":"string"},"parentId":{"type":"string"},"convertTo":{"type":"string"}}}}}},"responses":{"201":{"description":"The stored file","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FileItem"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}}},"/v1/files/folders":{"post":{"x-resource-group":"files","operationId":"createFolder","tags":["Files"],"summary":"Create a folder","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","name"],"properties":{"accountId":{"type":"string"},"name":{"type":"string","maxLength":255},"parentId":{"type":"string"}}}}}},"responses":{"201":{"description":"The folder","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FileItem"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}}},"/v1/files/picker-sessions":{"post":{"x-resource-group":"files","operationId":"createFilePickerSession","tags":["Files"],"summary":"Create a hosted Google Picker session","description":"Creates a hosted Google Picker session so your end user can grant Zernio access to Drive files.\n\nGoogle accounts are connected with `drive.file`, so Zernio opens only files it created or the user picked (see the Files tag).\n\n1. Create a session.\n2. Send the user to `url`.\n3. They pick files in Google Picker on a Zernio-hosted page.\n\n### Redirect\n\nWhen they finish, the browser is sent to `redirectUrl` with these query params added (existing params are kept):\n\n- `status=picked`, `pickerSessionId`, `fileIds` (comma-separated Drive file ids, already checked against Drive), or\n- `status=cancelled`, `pickerSessionId` when the user pressed Cancel.\n\nA `file.picked` webhook fires on every successful pick, so `redirectUrl` is optional for server-side integrations. Closing the picker without picking keeps the session open; the user can try again until it expires.\n\n### Limits\n\n- The URL is single-use and expires after 30 minutes; create a new session for every pick.\n- Google accounts only: Microsoft accounts answer 400 `platform_not_supported` because OneDrive needs no picker.\n- Picks are permanent grants: once picked, a file stays readable through the Files endpoints until the user removes Zernio from their Google account.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"A Google account connected with `scopes=files`."},"redirectUrl":{"type":"string","format":"uri","maxLength":2048,"description":"Where the browser goes when the user finishes. Absolute `http(s)` URL or a custom app scheme (`myapp://...`); relative, protocol-relative and script URLs are refused. Optional when you rely on the `file.picked` webhook."},"fileIds":{"type":"array","maxItems":50,"items":{"type":"string"},"description":"Drive file ids to show the user first (Google Picker `DocsView.setFileIds`), for example to ask for access to files your app already knows about. Pre-navigation only: the user still has to pick them."},"mimeTypes":{"type":"array","maxItems":30,"items":{"type":"string"},"example":["image/png","image/jpeg","application/pdf"],"description":"Only show files of these exact media types."},"multiselect":{"type":"boolean","default":true,"description":"false limits the pick to one file."}}},"example":{"accountId":"6650f1c2a4b5c6d7e8f90123","redirectUrl":"https://app.example.com/drive/picked","mimeTypes":["image/png","image/jpeg","video/mp4"]}}}},"responses":{"201":{"description":"The session","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FilePickerSession"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}}},"/v1/files/{fileId}":{"get":{"x-resource-group":"files","operationId":"getFile","tags":["Files"],"summary":"Get a file or folder","description":"On Google Drive, a file Zernio neither created nor was given through Google Picker answers 404 `resource_not_found` with `details: { fileId, reason: file_not_granted }`; send the user through `POST /v1/files/picker-sessions` (pass the id in `fileIds` to show it first). The same 404 applies to download, update, trash and share-link.","security":[{"bearerAuth":[]}],"parameters":[{"name":"fileId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/EmailAccountId"}],"responses":{"200":{"description":"The item","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FileItem"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}},"patch":{"x-resource-group":"files","operationId":"updateFile","tags":["Files"],"summary":"Rename or move a file","description":"`parentId` moves the item into another folder; `name` renames it. At least one is required.","security":[{"bearerAuth":[]}],"parameters":[{"name":"fileId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string"},"name":{"type":"string","maxLength":255},"parentId":{"type":"string"}}}}}},"responses":{"200":{"description":"The updated item","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FileItem"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}},"delete":{"x-resource-group":"files","operationId":"trashFile","tags":["Files"],"summary":"Move a file to the trash","description":"Drive trash or the OneDrive recycle bin; nothing is destroyed and the user can restore it on the provider.","security":[{"bearerAuth":[]}],"parameters":[{"name":"fileId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/EmailAccountId"}],"responses":{"200":{"description":"Trashed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"trashed":{"type":"boolean","description":"Always true."}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}}},"/v1/files/{fileId}/download":{"get":{"x-resource-group":"files","operationId":"downloadFile","tags":["Files"],"summary":"Download a file","description":"Streams the bytes with `Content-Disposition: attachment`. Google Docs, Slides and Drawings arrive as PDF/PNG and Sheets as XLSX, named with the export extension. Folders answer 400.","security":[{"bearerAuth":[]}],"parameters":[{"name":"fileId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/EmailAccountId"}],"responses":{"200":{"description":"The file bytes","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}}},"/v1/files/{fileId}/share-link":{"get":{"x-resource-group":"files","operationId":"getFileShareLink","tags":["Files"],"summary":"Get an anyone-with-the-link share link","description":"Grants read access to anyone holding the link (Drive `anyone` permission, OneDrive anonymous view link) and returns it. The grant stays until it is revoked on the provider.","security":[{"bearerAuth":[]}],"parameters":[{"name":"fileId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/EmailAccountId"}],"responses":{"200":{"description":"The link","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FileShareLink"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"412":{"$ref":"#/components/responses/MailboxPreconditionFailed"}}}},"/v1/connect/microsoft/admin-consent":{"get":{"x-resource-group":"accounts","operationId":"startMicrosoftAdminConsent","tags":["Connect"],"summary":"Admin-consent link for a Microsoft tenant","description":"Returns the Microsoft Entra admin-consent link for the app, so a tenant administrator can grant mail or calendar access.\n\nSome Microsoft 365 tenants let no user grant mail or calendar access themselves. The API then answers 412 `admin_consent_required` with `details.adminConsentUrl`, a ready admin-consent link.\n\nThis endpoint mints a fresh one (each is valid for one hour) and lets you choose `redirectUrl`.\n\n### Flow\n\n1. A tenant administrator opens the link and approves.\n2. They are sent to `redirectUrl` with `adminConsent=granted&tenant=…` (or `adminConsent=denied&error=…`).\n3. The grant is recorded on the account, and later requests succeed without a reconnect.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"redirectUrl","in":"query","schema":{"type":"string","format":"uri"},"description":"Where to send the administrator afterwards."}],"responses":{"200":{"description":"The link to hand to a tenant administrator","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"adminConsentUrl":{"type":"string","format":"uri"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/inbox/conversations":{"get":{"x-resource-group":"messages","operationId":"listInboxConversations","summary":"List conversations","description":"Fetch conversations (DMs) from all connected messaging accounts in a single API call. Supports filtering by profile and platform. Results are aggregated and deduplicated.\n\nSupported platforms: Facebook, Instagram, X, Bluesky, Reddit, Telegram, WhatsApp, iMessage and SMS.\n\n### X limitation\n\nX has replaced traditional DMs with encrypted \"X Chat\" for many accounts. Messages sent or received through encrypted X Chat are not accessible via X's API (the /2/dm_events endpoint only returns legacy unencrypted DMs).\n\nThis means some X conversations may show only outgoing messages or appear empty. This is an X platform limitation that affects all third-party applications. See X's docs on encrypted messaging for more details.\n\n### Instagram and Facebook pre-connect history\n\nWhen one of these accounts is connected, Zernio replays the DM history the account already holds on Meta, so conversations that began before the account was connected appear here. Up to 500 conversations per account are replayed.\n\n- The replay runs in the background and can finish after a listing you have already taken.\n- Replayed conversations keep their original lastMessageAt, so they sort into date order rather than appearing at the top.\n- If you mirror this endpoint into your own store, re-run the sweep rather than relying on a single pass at connect time.\n- Replayed history emits no webhooks and is stored as already read, so it never affects unread counts.\n- Threads that Meta refuses to serve are skipped.\n- An account whose Instagram \"connected tools\" message access is turned off is not replayed at all.\n","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Filter by profile ID"},{"name":"platform","in":"query","schema":{"type":"string","enum":["facebook","instagram","twitter","bluesky","reddit","telegram","whatsapp","imessage","sms"]},"description":"Filter by platform"},{"name":"status","in":"query","schema":{"type":"string","enum":["active","archived"]},"description":"Filter by conversation status"},{"name":"folder","in":"query","schema":{"type":"string","enum":["inbox","requests"],"default":"inbox"},"description":"`requests` lists Facebook Page Message Requests (threads from people the account has not accepted) live from Meta, each item with `folder: requests`.\n\nMeta has no accept call: replying moves a thread to the inbox, which is what POST /v1/inbox/conversations/{conversationId}/accept does.\n\n- When Meta will not list the folder for the one account asked (`accountId`), the call answers 400 PLATFORM_LIMITATION. Across several accounts, the refusal is reported per account in meta.failedAccounts.\n- Instagram accounts (Instagram Login and Facebook Login) answer PLATFORM_LIMITATION, because Meta does not separate the folder on Instagram. Only Facebook Pages are served.\n\nOne page of up to `limit` threads. `pagination.hasMore` is true when threads past `limit` were cut (narrow with `accountId`). `pagination.nextCursor` is always null and a `cursor` answers 400.\n"},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort order by updated time"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum number of conversations to return; values above 100 are served as 100."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for next page"},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Filter by specific account ID"},{"name":"tags","in":"query","schema":{"type":"string"},"description":"Comma-separated contact tags. Returns only conversations whose contact has any of them. Cannot be combined with folder=requests."}],"responses":{"200":{"description":"Aggregated conversations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Opaque conversation identifier. Pass it back verbatim to any /v1/inbox/conversations/{conversationId} route; do not assume a fixed format."},"platform":{"type":"string"},"accountId":{"type":"string"},"accountUsername":{"type":"string"},"pageId":{"type":["string","null"],"description":"The bare Facebook Page id behind the account, for Facebook and Instagram connected through Facebook Login. Null when the account has no Facebook Page."},"participantId":{"type":"string"},"participantName":{"type":"string"},"participantPicture":{"type":["string","null"]},"participantVerifiedType":{"type":["string","null"],"enum":["blue","government","business","none"],"description":"X verified badge type. Only present for X conversations."},"businessScopedUserId":{"type":"string","description":"WhatsApp only. Meta business-scoped user ID (BSUID), the stable identity anchor; present when Meta has sent it for this participant."},"whatsappUsername":{"type":"string","description":"WhatsApp only. The participant's WhatsApp username (e.g. `jane.shop`, no leading @). Not a stable identifier, because users can change it: useful for display, not recommended as an identity anchor. Captured from inbound messages, so older threads fill in on their next inbound."},"lastMessage":{"type":"string"},"updatedTime":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["active","archived"]},"unreadCount":{"type":["integer","null"],"maximum":1000,"description":"Number of unread incoming messages, capped at 1000. Read from a replica, so it can trail a conversation you just marked read by a few seconds."},"threadControl":{"type":"string","enum":["app","ai_agent","other"],"description":"Present once a handover has touched the thread (WhatsApp, Facebook, Instagram). ai_agent: Meta Business Agent answers (WhatsApp) and new inbound arrive flagged metadata.standby; app: you hold control; other: another app does (a WhatsApp partner, or a Messenger / Instagram receiver such as Page Inbox). Change it with POST /v1/inbox/conversations/{conversationId}/thread-control."},"folder":{"type":"string","enum":["requests"],"description":"Present only on items listed with folder=requests: a Message Request the account has not accepted yet."},"isGroup":{"type":"boolean","description":"iMessage only, true for a group thread. Manage it through the /v1/imessage/groups/{conversationId} endpoints."},"url":{"type":["string","null"],"description":"Direct link to open the conversation on the platform (if available)"},"instagramProfile":{"type":["object","null"],"description":"Instagram profile data for the participant. Only present for Instagram conversations.","properties":{"isFollower":{"type":["boolean","null"],"description":"Whether the participant follows your Instagram business account"},"isFollowing":{"type":["boolean","null"],"description":"Whether your Instagram business account follows the participant"},"followerCount":{"type":["integer","null"],"description":"The participant's follower count on Instagram"},"isVerified":{"type":["boolean","null"],"description":"Whether the participant is a verified Instagram user"},"fetchedAt":{"type":["string","null"],"format":"date-time","description":"When this profile data was last fetched from Instagram"}}},"metadata":{"$ref":"#/components/schemas/InboxConversationAdMetadata"},"adAttribution":{"$ref":"#/components/schemas/ConversationAdAttribution"}}}},"pagination":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}},"meta":{"type":"object","properties":{"accountsQueried":{"type":"integer"},"accountsFailed":{"type":"integer"},"failedAccounts":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string"},"accountUsername":{"type":["string","null"]},"platform":{"type":"string"},"error":{"type":"string"},"code":{"type":["string","null"],"description":"Error code if available"},"retryAfter":{"type":["integer","null"],"description":"Seconds to wait before retry (rate limits)"}}}},"lastUpdated":{"type":"string","format":"date-time"},"accountsSkipped":{"type":"array","description":"Connected accounts that were not queried: their platform does not support this feature, or the account is not enabled for it","items":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string"}}}}}}}}}}},"400":{"x-summary":"The query is invalid, the platform has no direct messages, or Meta will not list the requests folder: fix the request.","description":"Invalid query, a platform without direct messages (PLATFORM_NOT_SUPPORTED), or folder=requests on one account Meta will not list the folder for (PLATFORM_LIMITATION).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"}}},"post":{"x-resource-group":"messages","operationId":"createInboxConversation","summary":"Create conversation","description":"Start a direct message conversation with a user. If a conversation with that recipient already exists, the message is added to the existing thread.\n\nSupported platforms: X, Bluesky, Reddit, WhatsApp, SMS, Slack, iMessage, and email (Google and Microsoft accounts). Other platforms return PLATFORM_NOT_SUPPORTED.\n\n### Email (Google / Microsoft)\n\nPass the recipient address as participantId with `subject`, `message` and optionally `cc`. The mail is sent from the mailbox and mirrored into the inbox. The response names the inbox conversation it opened (the provider thread id, usable with the other inbox endpoints).\n\n- 412 `account_scope_missing`: the account was connected without the `email` area\n- 409: the account is disconnected\n- 402 `payment_required`: Gmail accounts need a card on file\n\nSends count toward the mailbox's daily cap and never toward managed messages.\n\n### iMessage\n\nPass the recipient as participantId: a phone number in international format (+15551234567) or an iMessage email. Senders ordered through Zernio can message contacts who never wrote to them.\n\n#### Opening message rules\n\nThe first message to such a contact must be plain text from an identifiable person or business opening a conversation.\n\nA cold introduction, including a sales one, is fine (\"Hi Mark, this is John from Pratt Media. I help local roofers get more leads. Would you be open to a quick chat?\").\n\nIt may not contain links, email addresses, phone numbers, prices or attachments (the provider's own rule for opening messages). One that does returns 400 with code `invalid_content` and a message saying what was flagged, and nothing is sent.\n\n#### New contact limits\n\nEach sender may open at most one new conversation every 15 minutes. A new sender warms up, allowing this many new conversations per 24 hours:\n\n- Days 1-2 after activation: 2\n- Days 3-4: 5\n- Days 5-7: 10\n- Days 8-14: 20\n- Days 15-21: 30\n- After that: 50\n\nBeyond that the request returns 429 with code `new_contact_limit` and a time to retry. The warm-up counts from when a sender ordered through Zernio went live. Senders registered from your own provider account are not warmed up by Zernio.\n\n#### Follow-ups before the contact replies\n\nUntil the contact replies, the thread accepts the opening and at most two follow-ups, at least 24 hours apart.\n\n- A follow-up sooner returns 429 `new_contact_limit` with the time to retry.\n- A fourth message returns 409 `recipient_must_message_first`.\n\nThe provider treats every message to a contact who has not replied as a new conversation.\n\nFollow-ups therefore follow the same content rule and count toward the 15-minute spacing and the daily warm-up like an opening. Once the contact has written, the thread behaves like any other and is not limited.\n\n#### Sender safety\n\nRecipients can report a first message as junk, and reports can get a sender blocked permanently, so keep the reply rate high (above roughly 30%).\n\n- A sender registered with your own provider account may lack the add-on for new contacts. Its sends to them return 409 `recipient_must_message_first`, and an opt-in link is the way in.\n- A contact who opted out returns 409 `recipient_opted_out`.\n\n### Slack\n\nPass a workspace member id as participantId (list them with GET /v1/accounts/{accountId}/slack-members). Zernio opens the DM channel with that member and sends the message. The thread then behaves like any other Slack conversation in the inbox. The member must belong to the connected workspace.\n\n### WhatsApp\n\nThis is the endpoint for sending an approved template message to a phone number. Put the recipient phone in participantId and provide:\n\n- templateName\n- templateLanguage\n- templateParams: variable values for the text header, body and dynamic URL buttons, in that order\n\nA template is required because WhatsApp does not permit freeform messages to open a conversation. A missing template returns TEMPLATE_REQUIRED.\n\n#### Template lookup\n\nBefore sending, Zernio must resolve an exact APPROVED template definition matching both templateName and templateLanguage. If Meta rejects that lookup, or the exact approved definition is absent, Zernio sends no message and returns the canonical platform error instead.\n\nLookup errors use code `platform_api_error`, type `platform_error`, and platform `whatsapp`. Sanitized Meta code, message, and `error_data.details` are returned in `platformError`. `details` identifies `phase: template_lookup`, the query-free endpoint, upstream status, and only safe provider usage or retry headers.\n\n#### Template headers, buttons and cards\n\n- Templates with media headers (image, video, document) are handled automatically: Zernio fills the header at send time with the approved template's sample asset.\n- To send a DIFFERENT asset per message (e.g. a distinct invoice PDF for each recipient), pass headerMedia with a public link (or a Meta media id); it overrides the sample for that send.\n- A template whose approved header format is LOCATION has no header asset to reconstruct: Meta only accepts the location at send time. Pass headerLocation (latitude and longitude required) whenever such a template is sent. headerMedia and headerLocation cannot both be supplied.\n- A button that carries its own value at send time (a copy-code button holding a Pix payment code or a coupon, a flow token) is sent with templateButtonParams, addressed by the button's index. templateParams covers text variables and dynamic URL buttons only.\n- CAROUSEL templates take per-card overrides via templateCards, each addressed by the card's card_index. Card body variables restart at {{1}} per card and cannot be expressed in the flat templateParams order.\n- Template fields are accepted on the JSON body only, not on multipart requests.\n\n#### Existing threads and the 24-hour window\n\nFor a number you already have a thread with, this sends the template into that thread. That makes it the way to re-engage a contact after the 24-hour customer-service window has closed. Once the recipient replies (opening the 24h window), send freeform messages with the send-message endpoint (POST /v1/inbox/conversations/{conversationId}/messages).\n\n#### Meta Direct Send\n\nWhatsApp Business Accounts eligible for Meta Direct Send can instead open a conversation with a business-initiated utility text message and no template. Pass category: 'utility' together with message (and no templateName). See the category field below.\n\n### X\n\n#### DM eligibility\n\nBefore sending, the endpoint checks if the recipient accepts DMs from your account (via the receives_your_dm field). If not, a 422 error with code DM_NOT_ALLOWED is returned. Skip this check with skipDmCheck: true if you have already verified eligibility.\n\n#### API tier requirement\n\nDM write endpoints require X API Pro tier ($5,000/month) or Enterprise access. This applies to BYOK (Bring Your Own Key) users who provide their own X API credentials.\n\n#### Rate limits (X only)\n\nX's DM API enforces, shared across all DM endpoints:\n\n- 200 requests per 15 minutes per connected X account\n- 1,000 per 24 hours per connected X account\n- 15,000 per 24 hours per X developer app\n\nThese limits do NOT apply to other platforms. WhatsApp sends are governed by Meta's per-number messaging tiers (unique business-initiated conversations per 24 hours) and per-number throughput instead.\n","tags":["Messages"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"The account ID to send from"},"participantId":{"type":"string","description":"Recipient identifier. Provide either this or participantUsername.\n\n- X: the numeric user ID.\n- WhatsApp and SMS: the recipient phone number in international format (digits, country code included).\n- Slack: the workspace member id (e.g. U01ABCDEF).\n- iMessage: a phone number in international format with the leading +, or an iMessage email.\n"},"participantUsername":{"type":"string","description":"Recipient handle/username, an X or Bluesky handle (with or without @) or a Reddit username (with or without u/). Resolved via lookup. Provide either this or participantId."},"message":{"type":"string","description":"Text content of the message. At least one of message, attachment, or (for WhatsApp) templateName is required. Required when category is set (a Direct Send utility message is a text message). Required on email accounts."},"subject":{"type":"string","maxLength":998,"description":"Email accounts only (Google / Microsoft). Subject of the new thread."},"cc":{"type":"array","maxItems":50,"items":{"type":"string","format":"email"},"description":"Email accounts only (Google / Microsoft). Extra recipients copied on the opening mail."},"skipDmCheck":{"type":"boolean","default":false,"description":"X only. Skip the receives_your_dm eligibility check before sending. Use if you have already verified the recipient accepts DMs."},"templateName":{"type":"string","description":"WhatsApp only. Name of the approved template to start the conversation with. Required for WhatsApp unless category is used instead (Direct Send). Cannot be combined with category."},"category":{"type":"string","enum":["utility"],"description":"WhatsApp only (Meta Direct Send). Combined with message and without templateName, starts the conversation with a business-initiated UTILITY message and no pre-approved template. Meta matches or auto-creates a template asynchronously.\n\n- The WhatsApp Business Account must be eligible for Direct Send; otherwise the send fails with an error telling you to use an approved message template instead.\n- Cannot be combined with templateName (templates are already categorized at creation).\n- Utility messages only: marketing content is not allowed under this category.\n- Accepted on the JSON body only, not on multipart requests.\n"},"linkPreview":{"type":"boolean","default":true,"description":"WhatsApp only. Set false to send the Direct Send (category: 'utility') text message without a link-preview thumbnail for the first URL in the text.\n\nDefaults to true, which is how every WhatsApp text has been sent to date. Does not apply to template sends. Accepted on the JSON body only, not on multipart requests.\n"},"templateLanguage":{"type":"string","description":"WhatsApp only. Template language code (e.g. en_US)."},"templateParams":{"type":"array","items":{"type":"string"},"description":"WhatsApp only. Template variable values as one flat array, in order of appearance across the whole template: text-header variables, then body variables, then one value per dynamic URL button (in button order).\n\nWorks with positional placeholders ({{1}}, {{2}}, ...) and named placeholders ({{name}}, {{company}}, as Meta Business Manager creates them); values fill named slots in order of appearance.\n\nExample: a body with {{1}}, {{2}} plus a URL button https://example.com/{{1}} takes three values: [body1, body2, buttonSuffix].\n\nFor positional templates the list must cover every slot. Fewer values than the header + body + dynamic URL-button count is rejected with 400 (code INVALID_TEMPLATE_PARAMS) naming the expected split, rather than filling a button URL from the wrong value.\n\nA dynamic URL button covered by templateButtonParams needs no value here, unless another uncovered dynamic URL button follows it (the override applies after slot numbering).\n\nTake no value here:\n\n- Media headers (image, video, document): filled automatically from the approved template. Use headerMedia to override the header asset per send.\n- Non-dynamic-URL buttons (copy-code, flow): use templateButtonParams.\n"},"templateButtonParams":{"type":"array","maxItems":10,"description":"WhatsApp only. Values for template buttons that take one at send time, each addressed by the button's position in the approved template.\n\nThis is the only way to send a copy-code button's payload (a Pix payment code, a coupon) or a flow token, since templateParams is a flat array of text variables covering dynamic URL buttons only.\n\n- A button here overrides what templateParams would derive for that index, so no button is sent twice.\n- Repeating an index within this array is rejected with 400.\n- Each index must name a button of the matching kind on the approved template. This is checked before the send and returns 400 (INVALID_TEMPLATE_BUTTON_PARAM) rather than a Meta rejection.\n","items":{"type":"object","required":["index","subType","value"],"properties":{"index":{"type":"integer","minimum":0,"maximum":9,"description":"Zero-based position of the button in the approved template's buttons."},"subType":{"type":"string","enum":["url","copy_code","flow"],"description":"The button kind, which decides how the value is sent: copy_code sends it as the coupon_code payload, flow as the flow token, url as the dynamic suffix appended to the button's base URL."},"value":{"type":"string","minLength":1,"description":"The value to send (e.g. the Pix copy-and-paste code for a copy_code button)."}}}},"templateCards":{"type":"array","maxItems":10,"description":"WhatsApp only. Per-card overrides for a CAROUSEL template, each addressed by the card's card_index.\n\nCarousel card body variables restart at {{1}} per card, so they cannot be expressed in the flat templateParams slot order; use this instead.\n\nRejected with 400 (INVALID_TEMPLATE_CARD_PARAM): a cardIndex naming a card the approved template lacks, a duplicate cardIndex, or a params count that does not match the card body's token count.\n","items":{"type":"object","required":["cardIndex"],"properties":{"cardIndex":{"type":"integer","minimum":0,"maximum":9,"description":"The card's card_index in the approved template."},"params":{"type":"array","items":{"type":"string"},"description":"Values for this card's own body variables, in the card's own {{1}}, {{2}}, ... order (or named-slot order of appearance)."},"headerMedia":{"type":"object","description":"Overrides this card's header asset for THIS send. Without it, the card's approved sample asset is sent.","required":["type"],"properties":{"type":{"type":"string","enum":["image","video","document"],"description":"Must match the card header's media type."},"link":{"type":"string","description":"Public URL of the asset to send. Must be reachable without auth."},"id":{"type":"string","description":"A Meta media id (from the media upload endpoint), as an alternative to link."}}},"buttons":{"type":"array","maxItems":2,"description":"Values for this card's own buttons, each addressed by the button's index within the card.","items":{"type":"object","required":["index","subType","value"],"properties":{"index":{"type":"integer","minimum":0,"maximum":1,"description":"Zero-based position of the button within the card's buttons."},"subType":{"type":"string","enum":["quick_reply","url"],"description":"The button kind, which decides how the value is sent."},"value":{"type":"string","minLength":1,"description":"The value to send (quick_reply payload, or the URL dynamic suffix)."}}}}}}},"headerMedia":{"type":"object","description":"WhatsApp only. Overrides a media-header template's header asset for THIS send, so a template with an image/video/document header can carry a different asset per message (e.g. each recipient their own invoice PDF). Without it, the template's approved sample asset is sent. Provide exactly one of link or id.","required":["type"],"properties":{"type":{"type":"string","enum":["image","video","document"],"description":"Must match the template header's media type."},"link":{"type":"string","description":"Public URL of the asset to send. Must be reachable without auth."},"id":{"type":"string","description":"A Meta media id (from the media upload endpoint), as an alternative to link."},"filename":{"type":"string","description":"Document display name shown to the recipient (e.g. \"Factura 0001-123.pdf\"). document type only; ignored for image/video."}}},"headerLocation":{"type":"object","description":"WhatsApp only. Required to send a template whose approved header format is LOCATION: Meta only accepts the location's lat/long at send time, never at template creation, so there is nothing to fill in automatically. Cannot be combined with headerMedia (a template has exactly one header).","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","description":"Latitude in decimal degrees."},"longitude":{"type":"number","description":"Longitude in decimal degrees."},"name":{"type":"string","description":"Location name shown to the recipient (e.g. a business name)."},"address":{"type":"string","description":"Location address shown to the recipient."}}}}}},"multipart/form-data":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"The account ID to send from"},"participantId":{"type":"string","description":"X numeric user ID of the recipient"},"participantUsername":{"type":"string","description":"X username (with or without @) of the recipient"},"message":{"type":"string","description":"Text content of the message"},"attachment":{"type":"string","format":"binary","description":"Media attachment (image or video). One attachment per message."},"skipDmCheck":{"type":"string","enum":["true","false"],"default":"false","description":"Skip the DM eligibility check"}}}}}},"responses":{"201":{"description":"Conversation created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"messageId":{"type":"string","description":"Platform message ID (dm_event_id)"},"conversationId":{"type":"string","description":"Platform conversation ID (dm_conversation_id). For WhatsApp, this is Zernio's internal conversation id (24-character hex) which matches the id returned by the list-conversations endpoint and the conversationId in the message.received and conversation.started webhooks; use it to correlate the created thread with inbound events."},"participantId":{"type":"string","description":"X numeric user ID of the recipient"},"participantName":{"type":["string","null"],"description":"Display name of the recipient"},"participantUsername":{"type":["string","null"],"description":"X username of the recipient"}}}}}}}},"400":{"x-summary":"The send is rejected: use a supported attachment and, for WhatsApp, an approved template whose variables match the definition.","description":"Validation error or platform not supported. Specific cases:\n\n- PLATFORM_LIMITATION: an attachment the platform does not accept.\n- TEMPLATE_REQUIRED: a template is required to start a WhatsApp conversation.\n- INVALID_TEMPLATE_PARAMS, INVALID_TEMPLATE_BUTTON_PARAM: template variables do not match the approved definition.\n- INVALID_TEMPLATE_HEADER: a required template header is missing or incompatible.\n- INVALID_TEMPLATE_CARD_PARAM: templateCards do not match the approved carousel definition.\n- category combined with templateName, or used on a non-WhatsApp account.\n- DIRECT_SEND_NOT_ELIGIBLE, DIRECT_SEND_BLOCKED: the WhatsApp Business Account is not eligible for Direct Send; Meta must grant or restore access.\n- DIRECT_SEND_LIMITED: temporary, lifts on its own.\n- invalid_content: an iMessage first message to a new contact breaks the content rule.\n","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["PLATFORM_NOT_SUPPORTED","PLATFORM_LIMITATION","TEMPLATE_REQUIRED","INVALID_TEMPLATE_PARAMS","INVALID_TEMPLATE_BUTTON_PARAM","INVALID_TEMPLATE_HEADER","INVALID_TEMPLATE_CARD_PARAM","DIRECT_SEND_NOT_ELIGIBLE","DIRECT_SEND_LIMITED","DIRECT_SEND_BLOCKED","invalid_content"]}}},{"$ref":"#/components/schemas/WhatsAppTemplateLookupError"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required, profile limit reached, or a sandbox send with a template other than the locked sandbox template"},"404":{"description":"Account or recipient user not found (Reddit: PARTICIPANT_NOT_FOUND when the u/username does not exist)","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["account_not_found","PARTICIPANT_NOT_FOUND"]}}},{"$ref":"#/components/schemas/WhatsAppTemplateLookupError"}]}}}},"409":{"x-summary":"The iMessage send was blocked because the contact opted out or must message the sender first: wait for the contact to write.","description":"iMessage only. The contact opted out of this sender (recipient_opted_out); or this contact has never written to the sender and either the sender lacks the add-on for new contacts or three messages already went out and the contact has not replied (recipient_must_message_first).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["recipient_opted_out","recipient_must_message_first"]}}}}}},"422":{"description":"Recipient does not accept DMs from this account (X), or does not accept direct messages from you (Reddit)","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["DM_NOT_ALLOWED"]}}},{"$ref":"#/components/schemas/WhatsAppTemplateLookupError"}]}}}},"429":{"x-summary":"A platform rate limit or new-contact limit was reached, or Meta rejected the template lookup and nothing was sent: retry later.","description":"X API rate limit exceeded, Reddit rate limit reached, Meta rejected the WhatsApp template-definition lookup (a lookup failure sends no message), or an iMessage sender reached its new-contact pacing or warm-up limit (new_contact_limit; the error says when to retry).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["rate_limited","new_contact_limit"]}}},{"$ref":"#/components/schemas/WhatsAppTemplateLookupError"}]}}}},"502":{"x-summary":"The WhatsApp account has no Business Account ID, so the template definition cannot be looked up and no message was sent.","description":"The WhatsApp account has no Business Account ID, so the template definition cannot be looked up (a template with no approved variant in that language is a 400). No message was sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhatsAppTemplateLookupError"}}}},"default":{"x-summary":"Meta rejected the WhatsApp template-definition lookup with an upstream status, and no message was sent: retry later.","description":"Meta rejected the WhatsApp template-definition lookup with another upstream status. No message was sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhatsAppTemplateLookupError"}}}}}}},"/v1/inbox/conversations/search":{"get":{"x-resource-group":"messages","operationId":"searchInboxConversations","summary":"Search conversations","description":"Search your conversations two ways at once, and get back the matching conversations, most-recent match first.\n\n### Message text\n\nMatches words inside message bodies. Case-insensitive and accent-insensitive, exact tokens only (no substrings, no stemming). Each hit carries up to 3 most-recent matching messages.\n\nWith direction=outgoing you can collect examples of how you write to customers, for example to teach an AI agent your tone of voice.\n\n### Contact identity\n\nMatches the participant's name, username, or phone number as a case-insensitive substring. These hits have matchCount 0 and an empty matches array.\n\nA conversation that matches both ways is returned once, carrying its message matches.\n\n### Searchable platforms\n\nOnly platforms whose messages are stored by Zernio are searchable: WhatsApp, SMS, Telegram, Facebook, Instagram, X and Reddit.\n\nBluesky conversations are fetched live from the platform and cannot be searched; those accounts are listed in meta.accountsSkipped.\n","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":200},"description":"Text to search for, in message content and in the contact's name, username, or phone number"},{"name":"direction","in":"query","schema":{"type":"string","enum":["incoming","outgoing"]},"description":"Only match messages sent to you (incoming) or by you (outgoing). Contact-identity matching is not applied when this is set."},{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Filter by profile ID"},{"name":"platform","in":"query","schema":{"type":"string","enum":["facebook","instagram","telegram","whatsapp","sms","rcs","slack","imessage"]},"description":"Filter by platform (searchable platforms only)"},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Filter by specific account ID"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Maximum number of conversations to return"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque pagination cursor. Pass back pagination.nextCursor verbatim; do not construct one."}],"responses":{"200":{"description":"Conversations containing the query, most recent match first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"conversation":{"type":"object","properties":{"id":{"type":"string","description":"Conversation ID, usable with the conversation messages endpoints"},"platform":{"type":"string"},"accountId":{"type":"string"},"participantName":{"type":["string","null"]},"participantUsername":{"type":["string","null"]},"participantPicture":{"type":["string","null"]},"businessScopedUserId":{"type":"string","description":"WhatsApp only. Meta business-scoped user ID (BSUID), the stable identity anchor; present when Meta has sent it for this participant."},"whatsappUsername":{"type":"string","description":"WhatsApp only. The participant's WhatsApp username (e.g. `jane.shop`, no leading @). Not a stable identifier, because users can change it: useful for display, not recommended as an identity anchor. Captured from inbound messages, so older threads fill in on their next inbound."},"status":{"type":"string","enum":["active","archived"]},"lastMessage":{"type":["string","null"],"description":"The conversation's most recent message preview"},"lastMessageAt":{"type":["string","null"],"format":"date-time"}}},"matchCount":{"type":"integer","description":"Number of matching messages in this conversation. 0 when the conversation matched only on contact identity (name, username, or phone number), not on message text."},"matches":{"type":"array","description":"Up to 3 most-recent matching messages (empty for an identity-only match)","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":["string","null"]},"direction":{"type":"string","enum":["incoming","outgoing"]},"timestamp":{"type":"string","format":"date-time"}}}}}}},"pagination":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}},"meta":{"type":"object","properties":{"accountsQueried":{"type":"integer"},"accountsFailed":{"type":"integer"},"failedAccounts":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string"},"accountUsername":{"type":["string","null"]},"platform":{"type":"string"},"error":{"type":"string"}}}},"lastUpdated":{"type":"string","format":"date-time"},"accountsSkipped":{"type":"array","description":"Connected messaging accounts that cannot be searched (live-fetched platforms)","items":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string"}}}}}}}}}}},"400":{"description":"Invalid query, unsupported platform, or malformed cursor"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"}}}},"/v1/inbox/conversations/{conversationId}":{"get":{"x-resource-group":"messages","operationId":"getInboxConversation","summary":"Get conversation","description":"Retrieve details and metadata for a specific conversation. Requires accountId query parameter.","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"Opaque conversation identifier, accepted verbatim from the list endpoint or from the conversationId on inbox webhooks. Format not to be assumed."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The account ID"}],"responses":{"200":{"description":"Conversation details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"accountUsername":{"type":"string"},"pageId":{"type":["string","null"],"description":"The bare Facebook Page id behind the account, for Facebook and Instagram connected through Facebook Login. Null when the account has no Facebook Page."},"platform":{"type":"string"},"status":{"type":"string","enum":["active","archived"]},"participantName":{"type":"string"},"participantId":{"type":"string"},"participantVerifiedType":{"type":["string","null"],"enum":["blue","government","business","none"],"description":"X verified badge type. Only present for X conversations."},"businessScopedUserId":{"type":"string","description":"WhatsApp only. Meta business-scoped user ID (BSUID), the stable identity anchor; present when Meta has sent it for this participant."},"whatsappUsername":{"type":"string","description":"WhatsApp only. The participant's WhatsApp username (e.g. `jane.shop`, no leading @). Not a stable identifier, because users can change it: useful for display, not recommended as an identity anchor. Captured from inbound messages, so older threads fill in on their next inbound."},"lastMessage":{"type":"string"},"lastMessageAt":{"type":"string","format":"date-time"},"updatedTime":{"type":"string","format":"date-time"},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"instagramProfile":{"type":["object","null"],"description":"Instagram profile data for the participant. Only present for Instagram conversations.","properties":{"isFollower":{"type":["boolean","null"],"description":"Whether the participant follows your Instagram business account"},"isFollowing":{"type":["boolean","null"],"description":"Whether your Instagram business account follows the participant"},"followerCount":{"type":["integer","null"],"description":"The participant's follower count on Instagram"},"isVerified":{"type":["boolean","null"],"description":"Whether the participant is a verified Instagram user"},"fetchedAt":{"type":["string","null"],"format":"date-time","description":"When this profile data was last fetched from Instagram"}}},"metadata":{"$ref":"#/components/schemas/InboxConversationAdMetadata"},"adAttribution":{"$ref":"#/components/schemas/ConversationAdAttribution"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"description":"Conversation not found"}}},"put":{"x-resource-group":"messages","operationId":"updateInboxConversation","summary":"Update conversation status","description":"Archive or activate a conversation. Requires accountId in request body.","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"Opaque conversation identifier, accepted verbatim from the list endpoint or from the conversationId on inbox webhooks. Format not to be assumed."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","status"],"properties":{"accountId":{"type":"string","description":"Account ID"},"status":{"type":"string","enum":["active","archived"]}}}}}},"responses":{"200":{"description":"Conversation updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"status":{"type":"string","enum":["active","archived"]},"platform":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"description":"Conversation not found (WhatsApp only; other platforms upsert)"}}},"delete":{"x-resource-group":"messages","operationId":"deleteInboxConversation","summary":"Delete conversation","description":"Permanently deletes Zernio's stored copy of one conversation and every message in it, in one transaction, and unlinks the contact channel that pointed at it.\n\n### What is kept\n\n- Nothing is deleted on the platform (the thread stays in WhatsApp, Messenger or Instagram).\n- The contact record is kept: call DELETE /v1/contacts/{contactId} to erase the person's name and number as well.\n\nInbound media copies Zernio stored are removed on a best-effort basis.\n\n### Re-imports\n\nA platform re-sync can import the thread again:\n\n- WhatsApp coexistence numbers receive their messaging history from Meta repeatedly.\n- A Facebook or Instagram account whose DM history walk has not finished imports it on that walk.\n","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"Opaque conversation identifier, accepted verbatim from the list endpoint or from the conversationId on inbox webhooks. Format not to be assumed."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Account ID"}],"responses":{"200":{"description":"Conversation deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"platform":{"type":"string"},"deletedMessages":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"description":"Account or conversation not found"}}}},"/v1/inbox/conversations/{conversationId}/messages":{"get":{"x-resource-group":"messages","operationId":"getInboxConversationMessages","summary":"List messages","description":"Fetch messages for a specific conversation, with cursor-based pagination and ordering control.\n\n### Pagination\n\nPass `pagination.nextCursor` from a prior response back as the `cursor` query param to fetch the next page. The cursor is opaque; do not parse or construct it client-side.\n\n### Sort order\n\nDefaults to `asc` (oldest first, chat style). For the \"show me the latest messages\" pattern, pass `?sortOrder=desc&limit=N`.\n\n- X, Instagram, Telegram, WhatsApp and Reddit honor the requested order from the local message store.\n- Facebook and Bluesky upstream APIs only return newest-first and have no order parameter. Sort order is best-effort and only reverses items within a single page (pages still walk newest→oldest).\n\nThe response field `sortOrderApplied` tells you what was actually applied.\n\n### Platform limits\n\n- **Reddit**: threads are paginated client-side because Reddit's API has no per-thread cursor. Very long threads may be upstream-truncated by Reddit's inbox/sent windows (~100 most-recent items each); this is a Reddit platform limitation.\n- **Instagram and Facebook**: conversations include history from before the account was connected, replayed from Meta. See below.\n- **X**: X's encrypted \"X Chat\" messages are not accessible via the API. Conversations where the other participant uses encrypted X Chat may only show your outgoing messages. See the list conversations endpoint for more details.\n\nThe Meta replay covers the 500 most recent messages per conversation: a longer thread keeps its newest 500 and older messages are not retrievable. Messages that arrived after the account was connected are unaffected. Replayed messages are stored as already read and emit no webhooks.\n\n### Read state\n\nThis endpoint is read-only and does NOT mark messages as read or send read receipts. To mark a conversation read (and send WhatsApp blue ticks on eligible accounts), call `POST /v1/inbox/conversations/{conversationId}/read`.\n","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"Opaque conversation identifier, accepted verbatim from the list endpoint or from the conversationId on inbox webhooks. Format not to be assumed."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Account ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Number of messages to return per page. Default 100, max 100."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination cursor. Pass `pagination.nextCursor` from a prior response verbatim: a cursor we cannot parse returns 400 rather than silently restarting from the first page."},{"name":"sortOrder","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"description":"Order of returned messages. Default `asc` (oldest first, chat style).\nX, Instagram, Telegram, WhatsApp and Reddit honor this order\nacross cursor pages. For Facebook and Bluesky, only intra-page\nordering is affected. Pages always walk newest→oldest. See\n`sortOrderApplied` in the response.\n"}],"responses":{"200":{"description":"Messages in conversation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"pagination":{"type":"object","properties":{"hasMore":{"type":"boolean","description":"Whether more messages are available beyond this page."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor to fetch the next page. `null` on the last page."}}},"sortOrderApplied":{"type":"string","enum":["asc","desc"],"description":"Sort order actually applied to the returned page. May\ndiffer from the requested `sortOrder` for Facebook and\nBluesky (always `desc` regardless of request).\n"},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The platform's own message id: the `wamid` on WhatsApp, the `mid` on Instagram and Facebook Messenger.\n\nIt is what `metadata.quotedMessageId` points at, the value to pass as `replyTo` on platforms that support quote-replies, and the `{messageId}` segment of the attachment-resolve URL.\n\nWebhooks deliver the same value as `message.platformMessageId`; this response has no field by that name.\n"},"conversationId":{"type":"string"},"accountId":{"type":"string"},"platform":{"type":"string"},"message":{"type":"string"},"senderId":{"type":"string"},"senderName":{"type":["string","null"]},"senderVerifiedType":{"type":["string","null"],"enum":["blue","government","business","none"],"description":"X verified badge type. Only present for X messages."},"direction":{"type":"string","enum":["incoming","outgoing"]},"createdAt":{"type":"string","format":"date-time"},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["image","video","audio","file","sticker","share","template","unsupported_type"],"description":"On Instagram and Facebook a shared reel, post or ad reaches Zernio with no type of its own (Meta's `unsupported_type`) and is resolved from the media's Content-Type at ingest into `image`, `video`, `audio` or `file` with `originalType: \"unsupported_type\"`. `unsupported_type` is returned only when the CDN could not be classified in time."},"originalType":{"type":"string","description":"Instagram and Facebook only, and present only when it differs from `type`. Meta's own type before normalization:\n\n- `ig_reel` and `reel` become `video`.\n- `ig_post`, `post`, `ig_story` and `story_mention` become `share`.\n\nA story mention is `type: \"share\"` with `originalType: \"story_mention\"`. Render on this field, since `share` alone is ambiguous.\n\n`originalType: \"unsupported_type\"` marks a share Meta did not classify, resolved by content type. `refreshUrl` cannot re-mint it (Meta answers `is_unsupported` with no attachments for the message node), so download it when the `message.received` webhook arrives.\n"},"mimeType":{"type":"string","description":"MIME type of the media when Zernio knows it. On Instagram and Facebook it is set for shares resolved by content type (`originalType: \"unsupported_type\"`)."},"url":{"type":"string","description":"Direct media link. On Instagram and Facebook this is a signed Meta CDN url that EXPIRES: use it now, do not store it. Persist `refreshUrl` instead."},"refreshUrl":{"type":["string","null"],"description":"Instagram and Facebook only. Endpoint that resolves this attachment to a working url every time, re-minting it from Meta when the stored one has expired. Safe to store and render indefinitely.\n\nException: an attachment with `originalType: \"unsupported_type\"`. Meta cannot re-serve those, so the endpoint answers 404 once the url has expired.\n"},"filename":{"type":["string","null"]},"previewUrl":{"type":["string","null"]},"payload":{"type":"object","additionalProperties":true,"description":"Template content (title, subtitle, image, buttons) when type is template"}}}},"subject":{"type":["string","null"],"description":"Reddit message subject"},"storyReply":{"type":"object","description":"Instagram only. Present when the message replies to one of the account's stories. Also set on history imported after connecting, read off Meta's `story.reply_to`.","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 roughly 24 hours after the story posted; fetch promptly or treat 404s as expected."}}},"isStoryMention":{"type":"boolean","description":"Instagram only. True when the message is the user mentioning the account in their own story. The story itself is the `share` attachment with `originalType: \"story_mention\"`. Also set on imported history, read off Meta's `story.mention`."},"noRenderableContent":{"type":"boolean","description":"Instagram and Facebook Messenger only; absent on other platforms. True when Meta withholds the content of this message from the API (its `is_unsupported` flag): `message` is empty, `attachments` is empty, and there is nothing to fetch, now or later.\n\nDistinguishes such a message from an ordinary empty one, such as a story reply with no text.\n"},"isEdited":{"type":"boolean","description":"True if the sender has edited this message at least once."},"editedAt":{"type":["string","null"],"format":"date-time","description":"When the most recent edit happened."},"editCount":{"type":"integer","description":"Total number of edits applied."},"editHistory":{"type":"array","description":"Every prior version of the message, oldest first.","items":{"$ref":"#/components/schemas/InboxMessageEditHistoryEntry"}},"isDeleted":{"type":"boolean","description":"True if the sender has deleted (unsent) this message. The original message and attachments fields remain populated."},"deletedAt":{"type":["string","null"],"format":"date-time"},"deliveryStatus":{"type":["string","null"],"enum":["sent","delivered","read","played","failed","deleted"],"description":"Lifecycle status for outgoing messages. Not all platforms emit every state (see webhook support matrix)."},"deliveredAt":{"type":["string","null"],"format":"date-time"},"readAt":{"type":["string","null"],"format":"date-time"},"sentAt":{"type":["string","null"],"format":"date-time","description":"Original send time for outgoing messages (used for Messenger watermark queries)."},"deliveryError":{"type":["object","null"],"description":"Populated when deliveryStatus === \"failed\".","properties":{"code":{"type":"integer"},"title":{"type":"string"},"message":{"type":"string"},"details":{"type":"string","description":"Platform's extended detail for `code` (WhatsApp: Meta's `error_data.details`), when the platform sent one. Absent on SMS."},"href":{"type":"string","format":"uri","description":"Link to the platform's documentation for `code`, when the platform sent one."}}},"reactions":{"type":"array","description":"Emoji reactions on this message (WhatsApp / Telegram). At most one per party in a 1:1 thread.","items":{"type":"object","properties":{"emoji":{"type":"string"},"fromMe":{"type":"boolean","description":"true if the connected account reacted, false if the contact did."},"reactedAt":{"type":"string","format":"date-time"}}}},"metadata":{"type":"object","description":"Platform-specific extras. Free-form, but commonly includes:\n\n- `quotedMessageId`: the `id` of the message this one replies to (delivered as `message.platformMessageId` on webhooks).\n- `waInteractive`: a compact descriptor of WhatsApp interactive content sent (buttons / list / cta_url / flow / location_request).\n- `metaInteractive`: outgoing Instagram/Facebook buttons, quickReplies and template, as sent.\n- `interactiveType` / `interactiveId`: for inbound interactive taps.\n- `source`: where the message reached us from, not who produced it (read `sentVia` for that). `whatsapp_business_app` / `coexistence_history` on a WhatsApp Coexistence number, `bulk-api` on a POST /v1/whatsapp/bulk send.\n","additionalProperties":true},"sentVia":{"type":["string","null"],"enum":["human","api","broadcast","sequence","workflow","comment_automation","bulk-api",null],"description":"Which Zernio surface produced this outgoing message: `human` (an\noperator in the Zernio inbox), `api` (a call to this API),\n`broadcast`, `sequence`, `workflow`, `comment_automation`, or\n`bulk-api` (POST /v1/whatsapp/bulk). Same vocabulary as the `source`\nfilter on the inbox analytics endpoints.\n\nAlways present, and `null` whenever the lineage is unknown: every\nincoming message, any outgoing message sent from the platform's own\napp, and every message stored before this field shipped\n(2026-08). Existing messages are NOT backfilled, so treat `null`\nas \"unknown\", never as \"sent by a human\".\n"}}}},"lastUpdated":{"type":"string","format":"date-time"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"502":{"$ref":"#/components/responses/UpstreamFailure"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}},"post":{"x-resource-group":"messages","operationId":"sendInboxMessage","summary":"Send message","description":"Send a message in a conversation. Supports text, attachments, quick replies, buttons, templates, and message tags. Attachment and interactive message support varies by platform.\n\n### Email threads (Google / Microsoft accounts)\n\nThe text is sent as a reply to the latest mail of the thread, in either direction, with its recipients and a \"Re:\" subject. `cc` adds recipients. `message` is required.\n\n- 400: attachments and `replyTo` are rejected here (use POST /v1/email/messages/{messageId}/reply for a reply with attachments)\n- 412 `account_scope_missing`: the account was connected without the `email` area\n- 409: the account is disconnected\n- 402: a Gmail account without a card on file\n\nMail sends count toward the mailbox's daily cap, never toward managed messages.\n\n### WhatsApp per-recipient rate limit\n\nWhatsApp caps how many messages you may send to the same recipient in a short window. It rejects the excess with error code `131056` (\"Too many messages sent to this recipient\").\n\nPace sends to a single recipient at roughly 10 per minute; bursts above that return a `400` with code `131056`. Sends to other recipients are unaffected, so parallelise across recipients rather than flooding one.\n\n### iMessage pacing\n\nMessages to contacts who have not written to the sender in the last 24 hours must be at least 2 minutes apart per sender.\n\nA send inside that window returns `429` with code `new_contact_limit` and the time to retry. Replies to contacts who wrote within the last day are not paced.\n\nA thread opened with `POST /v1/inbox/conversations` takes at most two follow-ups before the contact replies, at least 24 hours apart:\n\n- `429 new_contact_limit`: a follow-up sent sooner\n- `409 recipient_must_message_first`: a fourth message\n\nEach such follow-up counts as a new conversation:\n\n- No links, emails, phone numbers, prices or attachments (`400 invalid_content`).\n- It uses the sender's 15-minute spacing and daily warm-up (`429 new_contact_limit`).\n\nText must be shorter than 10,000 characters.\n\n### WhatsApp template messages\n\nTo send an approved template into this conversation (required when the 24-hour customer-service window is closed), use the `template` field with a single element carrying the template reference: `{ \"elements\": [{ \"name\": ..., \"language\": ..., \"components\": [...] }] }`. See the `template` field below for the exact shape.\n\nTo send a template to a phone number you have no conversation with yet, use the create-conversation endpoint (POST /v1/inbox/conversations) instead.\n\n#### Template lookup\n\nZernio resolves the exact APPROVED template name and language before any WhatsApp template send. A failed lookup or missing exact definition sends no message and returns code `platform_api_error`, type `platform_error`, and platform `whatsapp`.\n\nSanitized Meta code, message, and `error_data.details` are returned in `platformError`. `details` identifies `phase: template_lookup`, the query-free endpoint, upstream status, and only safe provider usage or retry headers.\n\n### WhatsApp interactive messages\n\nRich interactive messages (list, CTA URL, Flow, location request) are available via the `interactive` field. Tap events are delivered through the `message.received` webhook with WhatsApp-specific `metadata` fields (`interactiveType`, `interactiveId`, `flowResponseJson`, `flowResponseData`).\n\n### Idempotency\n\nSend an `Idempotency-Key` header to make retries safe (e.g. after a client-side timeout where delivery is unknown). Works for JSON and multipart (file upload) requests alike. Keys are retained for 24 hours.\n\n- Same key + same body: replays the original response (with `Idempotent-Replayed: true`) instead of sending the message a second time.\n- Same key + different body: returns 422.\n- A key still in flight: returns 409.\n\nOnly successful (2xx) responses are stored for replay. If the request throws or returns a non-2xx status, the key is released so the same key can be retried once the problem is fixed. The header therefore protects the \"request succeeded but the response was lost\" case.\n\nFor an ambiguous failure (a 5xx or a network timeout), reconcile before retrying. A failure after the platform already accepted the message also releases the key, so a blind retry could send it twice.\n\nList the conversation's messages first. Treat an empty result as inconclusive rather than as proof nothing was sent, since a send that failed while being recorded leaves no trace on our side.\n","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"Opaque conversation identifier, accepted verbatim from the list endpoint or from the conversationId on inbox webhooks. Format not to be assumed."},{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"Account ID"},"message":{"type":"string","description":"Message text"},"attachmentUrl":{"type":"string","description":"URL of the attachment to send (image, video, audio, or file). Must be publicly accessible. For binary file uploads, use multipart/form-data instead.\n\nOn WhatsApp, an image, video, or file combined with `buttons` renders as the header of one interactive reply-button message. Audio cannot be combined with buttons."},"category":{"type":"string","enum":["utility"],"description":"WhatsApp only (Meta Direct Send). Sends a business-initiated UTILITY message without an approved template, e.g. outside the 24-hour customer service window. Meta matches or auto-creates a template asynchronously.\n\n- The WhatsApp Business Account must be eligible for Direct Send; otherwise the send fails, telling you to use an approved message template.\n- Supported only for text messages (link preview ok) and interactive messages (reply buttons, CTA URL buttons, voice-call button, header of text/image/video/document).\n- Cannot be combined with template, attachments, location, or contacts.\n- Utility messages only; marketing content is not allowed.\n- Accepted on the JSON body only, not on multipart requests.\n"},"linkPreview":{"type":"boolean","default":true,"description":"WhatsApp and iMessage. Set false to send the message without a link-preview thumbnail. Ignored on other platforms.\n\n- WhatsApp: affects the first URL.\n- iMessage: every link renders as plain text.\n\nDefaults to true, which is how every WhatsApp text has been sent to date. Accepted on the JSON body only, not on multipart requests.\n"},"attachmentType":{"type":"string","enum":["image","video","audio","file"],"description":"Type of attachment. Defaults to file if not specified."},"attachmentName":{"type":"string","description":"WhatsApp only. Display name for a document sent via attachmentUrl with attachmentType: file (e.g. \"Report.pdf\"). Maps to the recipient's file name; without it WhatsApp derives the name from the URL and shows \"Untitled\". Ignored for image/video/audio and for binary uploads (which use the uploaded file's name)."},"voiceNote":{"type":"boolean","description":"WhatsApp only. When `true` on an audio attachment, the message is sent as a voice message (PTT): the recipient sees the waveform + voice-note UI instead of a basic audio attachment. Ignored for non-audio attachments.\n\nThe audio file MUST be `.ogg` encoded with the OPUS codec (mono), per Meta's voice-message contract; other formats are rejected by WhatsApp.\n"},"subject":{"type":"string","maxLength":1000,"description":"iMessage only (JSON body only). Bold title line rendered above the message text. Rejected with 400 on other platforms; ignored on voice-message sends."},"cc":{"type":"array","maxItems":50,"items":{"type":"string","format":"email"},"description":"Email threads only (Google / Microsoft accounts, JSON body only). Extra recipients copied on the reply."},"effect":{"type":"string","enum":["slam","loud","gentle","invisibleInk","echo","spotlight","balloons","confetti","love","lasers","fireworks","shootingStar","celebration"],"description":"iMessage only (JSON body only). Apple screen/bubble animation played when the message arrives. Rejected with 400 on other platforms."},"contactCard":{"type":"boolean","description":"iMessage only (JSON body only). When `true`, attaches the sender's contact card (vCard) so the recipient can save the sender. Counts as message content on its own, so `message` becomes optional."},"channel":{"type":"string","enum":["imessage","sms","rcs","whatsapp"],"description":"iMessage only (JSON body only). Overrides the delivery channel for this one send; the provider otherwise picks it automatically. The sender must carry the matching add-on (SMS, RCS or WhatsApp), or the send fails. Not a default to set on every request. Rejected with 400 on other platforms."},"sharedMediaId":{"type":"string","pattern":"^\\d+$","example":"17895695668004550","description":"Instagram only (JSON body only; 400 on other platforms). Shares one of the account's own published posts in the DM, by its Instagram media id (the `id` returned by the media endpoints, not a permalink). Meta only accepts media the account owns.\n\nSent on its own: cannot be combined with `message`, attachments, `quickReplies`, `buttons`, `template` or `sticker` (400). `messageTag: HUMAN_AGENT` is allowed. Works on accounts connected with Instagram Login and with Facebook Login.\n"},"sticker":{"type":"string","enum":["like_heart"],"description":"Instagram only (JSON body only). Sends a sticker instead of text; `like_heart` is the heart sticker. Sent on its own: cannot be combined with `message`, attachments, `quickReplies`, `buttons`, `template` or `sharedMediaId` (400). `messageTag: HUMAN_AGENT` is allowed. Rejected with 400 on other platforms."},"quickReplies":{"type":"array","maxItems":13,"description":"Quick reply buttons. Mutually exclusive with buttons. Max 13 items.","items":{"type":"object","required":["title","payload"],"properties":{"title":{"type":"string","maxLength":20,"description":"Button label (max 20 chars)"},"payload":{"type":"string","description":"Payload sent back on tap"},"imageUrl":{"type":"string","description":"Optional icon URL (Meta only)"}}}},"buttons":{"type":"array","maxItems":3,"description":"Action buttons. Max 3 items. Mutually exclusive with quickReplies.\n\n**Instagram / Facebook.** Also mutually exclusive with `template`: a Meta message carries one body shape, so sending both is a 400 rather than a silent drop of the buttons.\n\nThe buttons and `message` render as Meta's button_template (one bubble with the text and the buttons below it), so `message` must be 640 characters or less when buttons are attached (400 otherwise).\n\n**WhatsApp.** Buttons always render as interactive reply buttons. Only `title` and `payload` are used; `type`, `url`, and `phone` are ignored. WhatsApp has no URL/phone button in this field: use the `interactive` field with `type: cta_url` for a link button.\n\n`payload` becomes the button reply ID delivered on the `message.received` webhook when the user taps. For a simple reply-button message, provide `title` + `payload` and set `type: postback`, e.g. `{ \"type\": \"postback\", \"title\": \"Yes\", \"payload\": \"yes\" }`.\n\nCombine `buttons` with `attachmentUrl` and `attachmentType` `image`, `video`, or `file` to render one WhatsApp message with a media header, body text and reply buttons. Audio is not a supported interactive header and returns 400 when combined with buttons.\n","items":{"type":"object","required":["type","title"],"properties":{"type":{"type":"string","enum":["url","postback","phone"],"description":"Button type. phone is Facebook only. Ignored on WhatsApp (buttons always render as reply buttons)."},"title":{"type":"string","maxLength":20,"description":"Button label (max 20 chars)"},"url":{"type":"string","description":"URL for url-type buttons (Facebook/Instagram only)"},"payload":{"type":"string","description":"Payload for postback-type buttons. On WhatsApp, this is the reply ID returned on the message.received webhook when the button is tapped."},"phone":{"type":"string","description":"Phone number for phone-type buttons (Facebook only)"}}}},"template":{"type":"object","description":"Platform-dependent template payload. Ignored on Telegram.\n\n**Instagram / Facebook:** a generic template (carousel). Set `type: generic` and provide up to 10 `elements`, each with a `title` (required) and optional `subtitle`, `imageUrl`, and `buttons`.\n\n- Mutually exclusive with the top-level `buttons` field (sending both is a 400); put card buttons on its `elements`.\n- On Facebook, `imageAspectRatio` (`horizontal`, the default, or `square`) sets how Messenger renders element images. Instagram has no such setting and rejects it.\n\n**WhatsApp:** sends an approved template message, the only type WhatsApp accepts when the 24-hour customer-service window is closed. Provide exactly one element with the template reference (`type` is ignored):\n\n`{ \"elements\": [{ \"name\": \"order_update\", \"language\": \"en_US\", \"components\": [...] }] }`\n\n`components` is optional and forwarded unchanged as the `template.components` array of Meta's Cloud API send payload. Use it to fill body/header variables and button parameters, e.g. `[{ \"type\": \"body\", \"parameters\": [{ \"type\": \"text\", \"text\": \"John\" }] }]`.\n\nTemplates with media headers (image, video, document) must include the header component with its media link at send time. To message a phone number with no conversation, or have media headers filled automatically, use the create-conversation endpoint (POST /v1/inbox/conversations).\n","properties":{"type":{"type":"string","enum":["generic"],"description":"Template type. Required for Instagram/Facebook generic templates; ignored on WhatsApp."},"imageAspectRatio":{"type":"string","enum":["horizontal","square"],"description":"Facebook only. Aspect ratio Messenger renders element images at: horizontal (1.91:1, default) or square (1:1). A 400 on Instagram."},"elements":{"type":"array","maxItems":10,"items":{"type":"object","properties":{"title":{"type":"string","maxLength":80,"description":"Element title (max 80 chars). Required for Instagram/Facebook generic templates."},"subtitle":{"type":"string","description":"Element subtitle (Instagram/Facebook only)"},"imageUrl":{"type":"string","description":"Element image URL (Instagram/Facebook only)"},"buttons":{"type":"array","maxItems":3,"description":"Element buttons (Instagram/Facebook only)","items":{"type":"object","properties":{"type":{"type":"string","enum":["url","postback"]},"title":{"type":"string","maxLength":20},"url":{"type":"string"},"payload":{"type":"string"}}}},"name":{"type":"string","description":"WhatsApp only. Name of the approved template to send."},"language":{"type":"string","description":"WhatsApp only. Template language code (e.g. en_US)."},"components":{"type":"array","description":"WhatsApp only. Meta Cloud API send-shape components array, forwarded to Meta verbatim.","items":{"type":"object","additionalProperties":true}}}}}}},"interactive":{"type":"object","description":"WhatsApp only. Rich interactive payload for list messages, CTA URL buttons, Flow prompts, location requests, voice-call buttons and commerce messages (single product, product list, catalog, carousel). The shape mirrors Meta's Cloud API `interactive` object for the types in the enum below.\n\nWhen set, it takes priority over `buttons` and `quickReplies`. For simple button replies (WhatsApp's `interactive.type: \"button\"`) use `buttons` / `quickReplies` instead: that abstraction caps at 3 buttons and handles the auto-conversion for you. Use this field only for the enum types.\n\nAll interactive messages are session messages: they can only be sent inside the 24-hour customer service window opened by the user's last inbound message.\n\nCommerce types (`product`, `product_list`, `catalog_message`, and product carousels) require a Meta catalog connected to the WhatsApp Business Account in Commerce Manager. Media carousels (image/video cards) do not need a catalog.\n\nRules per type:\n\n- `product`: `body` is optional (WhatsApp renders the product card itself) and `header` is not allowed (the product image is the header).\n- `product_list`: a `header` with `type: \"text\"` is required.\n- `carousel`: top-level `header`/`footer` are not supported; media goes on each card instead.\n- `voice_call`: renders WhatsApp's native call button; tapping it starts a voice call to your business number. Requires WhatsApp Business Calling on the sending number. The optional `parameters.payload` string is echoed back on the `calls` webhook (as `cta_payload`) for attribution.\n- `location_request_message`: `action` may be omitted (we default it to `{ \"name\": \"send_location\" }`). WhatsApp renders a localized \"Send location\" button; the reply arrives as a regular location message in the conversation.\n- `request_contact_info`: `action` may be omitted (we default it to `{ \"name\": \"request_contact_info\" }`). The localized share button cannot be relabelled, so put the reason for asking in `body.text`: this is a consent prompt, and a bare request converts badly.\n- `request_contact_info` reply: arrives as an inbound `contacts` message with `metadata.contactsOrigin` set to `contact_request`, and we fold the shared number back into the contact automatically. A `contacts` message with origin `other` is a card picked from the address book, NOT proof of the user's own number.\n- `catalog_message`: `action` may also be omitted (we default it to `{ \"name\": \"catalog_message\" }`).\n- `address_message`: `parameters.country` is required (Meta rejects the whole send without it); everything else in `parameters` (`values`, `saved_addresses`, `validation_errors`) is forwarded to Meta as-is.\n- `address_message` availability: Meta's native structured shipping-address capture, generally available in India as of 2026-08. Check Meta's documentation for current country availability before relying on it elsewhere.\n- `address_message` reply: the submitted address arrives as an `nfm_reply` on the `message.received` webhook, like a Flow submission, but with `metadata.nfmReplyName` set to `address_message` so you can tell the two apart.\n\nTap events come back via the `message.received` webhook with `metadata.interactiveType` set to `list_reply` or `nfm_reply`. Carts submitted from commerce messages arrive as `metadata.order`; product inquiries arrive as `metadata.referredProduct`.\n","required":["type"],"properties":{"type":{"type":"string","enum":["list","cta_url","flow","location_request_message","request_contact_info","voice_call","product","product_list","catalog_message","carousel","address_message"],"description":"Which interactive layout to render."},"header":{"type":"object","description":"Optional header shown above the body. Required with\n`type: \"text\"` for `product_list`; not allowed for `product`\nor `carousel`.\n","properties":{"type":{"type":"string","enum":["text","image","video","document"]},"text":{"type":"string","description":"Required when header type is text."},"image":{"type":"object","properties":{"link":{"type":"string"}}},"video":{"type":"object","properties":{"link":{"type":"string"}}},"document":{"type":"object","properties":{"link":{"type":"string"}}}}},"body":{"type":"object","description":"Required for every type except `product`, where it is optional.","required":["text"],"properties":{"text":{"type":"string","description":"Main body text."}}},"footer":{"type":"object","description":"Optional footer shown below the action.","properties":{"text":{"type":"string"}}},"action":{"oneOf":[{"type":"object","description":"List action. `type` on the parent must be `list`.","required":["button","sections"],"properties":{"button":{"type":"string","description":"CTA label that opens the list (max ~20 chars)."},"sections":{"type":"array","minItems":1,"maxItems":10,"description":"1-10 sections. Total rows across all sections cannot exceed 10.","items":{"type":"object","required":["rows"],"properties":{"title":{"type":"string","description":"Optional section header (max 24 chars)."},"rows":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"object","required":["id","title"],"properties":{"id":{"type":"string","description":"Identifier returned in the webhook as metadata.interactiveId (max 200 chars)."},"title":{"type":"string","description":"Row label (max 24 chars)."},"description":{"type":"string","description":"Optional description below the title (max 72 chars)."}}}}}}}}},{"type":"object","description":"CTA URL action. `type` on the parent must be `cta_url`.","required":["name","parameters"],"properties":{"name":{"type":"string","enum":["cta_url"]},"parameters":{"type":"object","required":["display_text","url"],"properties":{"display_text":{"type":"string","description":"Button label (max 20 chars)."},"url":{"type":"string","format":"uri","description":"Target URL opened when the user taps the button."}}}}},{"type":"object","description":"Voice-call action. `type` on the parent must be `voice_call`. Renders WhatsApp's native call button (requires Calling enabled on the sending number).","required":["name"],"properties":{"name":{"type":"string","enum":["voice_call"]},"parameters":{"type":"object","description":"All optional.","properties":{"display_text":{"type":"string","maxLength":20,"description":"Button label. Defaults to \"Call Now\"."},"ttl_minutes":{"type":"integer","minimum":1,"maximum":43200,"description":"How long the button stays tappable. Defaults to 10080 (7 days)."},"payload":{"type":"string","maxLength":512,"description":"Arbitrary string echoed back as `cta_payload` on the `calls` webhook (connect/terminate) for attribution."}}}}},{"type":"object","description":"Flow action. `type` on the parent must be `flow`.","required":["name","parameters"],"properties":{"name":{"type":"string","enum":["flow"]},"parameters":{"type":"object","required":["flow_token","flow_id","flow_cta","flow_action"],"properties":{"flow_message_version":{"type":"string","enum":["3"],"description":"Defaults to \"3\" when omitted."},"flow_token":{"type":"string","description":"Opaque token you choose to correlate Flow responses with your own state (max 200 chars)."},"flow_id":{"type":"string","description":"Published Flow ID from Meta Business Manager."},"flow_cta":{"type":"string","description":"Button label that opens the Flow (max 20 chars)."},"flow_action":{"type":"string","enum":["navigate","data_exchange"],"description":"`navigate` sends the user to `flow_action_payload.screen`; `data_exchange` posts data to your Flow endpoint."},"flow_action_payload":{"type":"object","description":"Required when flow_action is `navigate`.","properties":{"screen":{"type":"string","description":"First screen to show."},"data":{"type":"object","additionalProperties":true,"description":"Optional pre-filled data passed to the screen."}}},"mode":{"type":"string","enum":["draft"],"description":"Set to `draft` to test an unpublished Flow."}}}}},{"type":"object","description":"Location request action. `type` on the parent must be `location_request_message`. May be omitted entirely; it is defaulted.","required":["name"],"properties":{"name":{"type":"string","enum":["send_location"]}}},{"type":"object","description":"Contact-info request action. `type` on the parent must be `request_contact_info`. May be omitted entirely; it is defaulted.","required":["name"],"properties":{"name":{"type":"string","enum":["request_contact_info"]}}},{"type":"object","description":"Single-product action. `type` on the parent must be\n`product`. Requires a Meta catalog connected to the\nWhatsApp Business Account in Commerce Manager.\n","required":["catalog_id","product_retailer_id"],"properties":{"catalog_id":{"type":"string","description":"Meta catalog ID connected to the WhatsApp Business Account."},"product_retailer_id":{"type":"string","description":"Retailer ID (SKU) of the product inside the catalog."}}},{"type":"object","description":"Multi-product action. `type` on the parent must be\n`product_list`. Requires a Meta catalog connected to the\nWhatsApp Business Account in Commerce Manager.\n","required":["catalog_id","sections"],"properties":{"catalog_id":{"type":"string","description":"Meta catalog ID connected to the WhatsApp Business Account."},"sections":{"type":"array","minItems":1,"maxItems":10,"description":"1-10 sections. Total products across all sections cannot exceed 30.","items":{"type":"object","required":["product_items"],"properties":{"title":{"type":"string","description":"Optional section header."},"product_items":{"type":"array","minItems":1,"items":{"type":"object","required":["product_retailer_id"],"properties":{"product_retailer_id":{"type":"string","description":"Retailer ID (SKU) of the product inside the catalog."}}}}}}}}},{"type":"object","description":"Catalog-message action. `type` on the parent must be\n`catalog_message`. May be omitted entirely; it is defaulted\nto `{ \"name\": \"catalog_message\" }`. Requires a Meta catalog\nconnected to the WhatsApp Business Account in Commerce\nManager.\n","required":["name"],"properties":{"name":{"type":"string","enum":["catalog_message"]},"parameters":{"type":"object","properties":{"thumbnail_product_retailer_id":{"type":"string","description":"Optional product whose image is used as the message thumbnail. Falls back to the first catalog item when omitted."}}}}},{"type":"object","description":"Carousel action. `type` on the parent must be `carousel`. Carries 2-10 cards, either:\n\n- all product cards (`type: \"product\"`, all referencing the same `catalog_id`); or\n- media cards (any other `type`, e.g. `cta_url`), each with a required image/video `header`.\n\n`card_index` (0-9, non-repeating) is auto-filled sequentially when omitted.\n\nProduct carousels require a Meta catalog connected to the WhatsApp Business Account in Commerce Manager; media carousels do not.\n","required":["cards"],"properties":{"cards":{"type":"array","minItems":2,"maxItems":10,"items":{"type":"object","additionalProperties":true,"properties":{"card_index":{"type":"integer","minimum":0,"maximum":9,"description":"Card position. Auto-filled sequentially when omitted."},"type":{"type":"string","description":"`product` for a product card; media cards use `cta_url` or a quick-reply type."},"header":{"type":"object","description":"Media cards only, required. Carries the card's image or video."},"body":{"type":"object","description":"Optional card body text."},"action":{"type":"object","description":"Product cards: `{ catalog_id, product_retailer_id }` (required). Media cards: the card's button action (e.g. `cta_url` with `parameters.display_text` and `parameters.url`)."}}}}}},{"type":"object","description":"Address-request action. `type` on the parent must be\n`address_message`. Renders Meta's native structured\naddress form in-chat (generally available in India as\nof 2026-08; check Meta's documentation for current\ncountry availability).\n","required":["name","parameters"],"properties":{"name":{"type":"string","enum":["address_message"]},"parameters":{"type":"object","required":["country"],"properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code Meta should localize the address form for (e.g. IN). Required: Meta rejects the send without it."},"values":{"type":"object","additionalProperties":true,"description":"Optional pre-filled address field values."},"saved_addresses":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Optional list of the recipient's previously saved addresses to offer as quick picks."},"validation_errors":{"type":"object","additionalProperties":{"type":"string"},"description":"Optional per-field error messages to show when re-prompting after a failed validation."}}}}}]}}},"replyMarkup":{"type":"object","description":"Telegram-native keyboard markup. Ignored on other platforms.","properties":{"type":{"type":"string","enum":["inline_keyboard","reply_keyboard"],"description":"Keyboard type"},"keyboard":{"type":"array","description":"Array of rows, each row is an array of buttons","items":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string","description":"Button text"},"callbackData":{"type":"string","maxLength":64,"description":"Callback data (inline_keyboard only, max 64 bytes)"},"url":{"type":"string","description":"URL to open (inline_keyboard only)"}}}}},"oneTime":{"type":"boolean","default":true,"description":"Hide keyboard after use (reply_keyboard only)"}}},"messagingType":{"type":"string","enum":["RESPONSE","UPDATE","MESSAGE_TAG"],"description":"Facebook messaging type. Required when using messageTag."},"messageTag":{"type":"string","enum":["CONFIRMED_EVENT_UPDATE","POST_PURCHASE_UPDATE","ACCOUNT_UPDATE","HUMAN_AGENT"],"description":"Facebook and Instagram. To reply after the 24h window, send HUMAN_AGENT with messagingType MESSAGE_TAG: it works up to 7 days after the person's last message, for replies typed by a person only (Meta does not allow it on automated messages). Meta retired the other tags, so they fail."},"replyTo":{"type":"string","description":"Platform message ID to quote-reply to.\n\n- WhatsApp: the wamid.\n- Telegram: the Telegram message ID (message.platformMessageId on webhooks, and `id` on each entry of the list-messages endpoint).\n- Slack: threads the reply (thread_ts) instead of quoting.\n- Instagram and Facebook Messenger: no send-side quote replies. The message is sent without a quote and the successful response includes a warnings entry with code ignored_field and param replyTo.\n- Other platforms without send-side reply support ignore this field.\n"},"location":{"type":"object","description":"WhatsApp and iMessage. Send a location pin (on iMessage it renders as a native map bubble).","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","description":"Latitude in decimal degrees."},"longitude":{"type":"number","description":"Longitude in decimal degrees."},"name":{"type":"string","description":"Optional location name."},"address":{"type":"string","description":"Optional street address."}}},"contacts":{"type":"array","description":"WhatsApp-only. Send one or more contact cards.","items":{"type":"object","required":["name"],"properties":{"name":{"type":"object","required":["formatted_name"],"properties":{"formatted_name":{"type":"string","description":"Full display name."},"first_name":{"type":"string"},"last_name":{"type":"string"}}},"phones":{"type":"array","items":{"type":"object","properties":{"phone":{"type":"string"},"type":{"type":"string","description":"e.g. CELL, WORK, HOME."}}}},"emails":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"type":{"type":"string"}}}}}}}}},"examples":{"whatsappImageWithReplyButtons":{"summary":"WhatsApp image, body text, and reply buttons","description":"The recipient sees one WhatsApp message containing the property\nimage as its header, \"Reply yes to continue.\" as the body, and\ntwo tappable reply buttons labelled Yes and No. A tap arrives on\nthe `message.received` webhook as `metadata.interactiveType:\nbutton_reply`; `metadata.interactiveId` is `btn_0` or `btn_1`.\n","value":{"accountId":"6a7adc04d0fe733d1a1bed76","message":"Reply yes to continue.","attachmentUrl":"https://cdn.example.com/property.jpg","attachmentType":"image","buttons":[{"type":"postback","title":"Yes","payload":"btn_0"},{"type":"postback","title":"No","payload":"btn_1"}]}}}},"multipart/form-data":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"Account ID"},"message":{"type":"string","description":"Message text (optional when sending attachment)"},"attachment":{"type":"string","format":"binary","description":"File attachment (images, videos, documents). Supported formats: JPEG, PNG, GIF, MP4, AAC, WAV. Max 25MB. On WhatsApp, combining an image, video, or document upload with buttons renders the upload as the interactive message header; audio plus buttons is rejected."},"quickReplies":{"type":"string","description":"JSON string of quick replies array (same schema as application/json body)"},"buttons":{"type":"string","description":"JSON string of buttons array (same schema as application/json body). On WhatsApp, an accompanying image, video, or document attachment becomes the interactive message header."},"template":{"type":"string","description":"JSON string of template object (same schema as application/json body)"},"replyMarkup":{"type":"string","description":"JSON string of replyMarkup object (same schema as application/json body)"},"messagingType":{"type":"string","description":"Messaging type (Facebook only). RESPONSE, UPDATE, or MESSAGE_TAG."},"messageTag":{"type":"string","description":"Message tag (requires messagingType MESSAGE_TAG)"},"replyTo":{"type":"string","description":"Platform message ID to quote-reply to.\n\n- WhatsApp: pass the wamid.\n- Telegram: the Telegram message ID (delivered as message.platformMessageId on webhooks, and as `id` on each entry of the list-messages endpoint).\n- Slack: threads the reply (thread_ts) instead of quoting.\n- Instagram and Facebook Messenger: no send-side quote replies. The message is sent without a quote, and the successful response includes a warnings entry with code ignored_field and param replyTo.\n- Other platforms without send-side reply support ignore this field.\n"},"voiceNote":{"type":"string","enum":["true"],"description":"WhatsApp-only. Set to \"true\" when the audio attachment is an in-browser voice recording; the server transcodes it to a WhatsApp-native container (ogg/Opus). Omit for regular audio file uploads."}}}}}},"responses":{"200":{"description":"Message sent","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"warnings":{"type":"array","description":"Present when a successful send ignored replyTo on Instagram or Facebook Messenger. The message was sent without a quote; do not retry it to apply the reply.","items":{"type":"object","required":["code","param","message"],"properties":{"code":{"type":"string","enum":["ignored_field"]},"param":{"type":"string","enum":["replyTo"]},"message":{"type":"string","description":"Human-readable explanation of the ignored field."}}}},"data":{"type":"object","properties":{"messageId":{"type":"string","description":"Platform id of the sent message (not returned for Reddit). For WhatsApp this is the raw Meta wamid, the same id delivered as message.platformMessageId on webhooks and delivery-status updates, and the value to pass as replyTo to quote-reply."},"conversationId":{"type":"string","description":"Zernio conversation id, echoed so the thread can be read back or replied to. Omitted when the send succeeded but the conversation could not be resolved to a stored record.\n\n- Telegram, WhatsApp, SMS and Slack: equals the id the list-conversations endpoint returns.\n- Facebook, Instagram, Bluesky and Reddit: that endpoint returns the platform thread id instead, so do not correlate the two by equality.\n- X: when the request addressed the conversation by its Twitter dm_conversation_id, that platform id is echoed back instead.\n"},"attachments":{"type":"array","description":"Echo of the sent attachment with its resolved public URL, when one is available (Facebook, Instagram, Telegram, WhatsApp).","items":{"type":"object","properties":{"type":{"type":"string"},"url":{"type":"string"}}}},"messageIds":{"type":"array","description":"Facebook/Instagram only. Present when an attachment and text were both requested: Meta has no single body shape for both, so the send is two Meta messages under the hood. First element === messageId (the attachment); second is the follow-up text.","items":{"type":"string"}},"partialFailure":{"type":"object","description":"Facebook/Instagram only. The attachment was delivered but the follow-up text message was rejected by Meta and was not stored; the response is still a 200 because the attachment send succeeded.","properties":{"part":{"type":"string","enum":["text"]},"error":{"type":"string"},"platformError":{"type":"object","description":"Meta's own diagnostic fields for the rejected follow-up, same shape as the 400 response's platformError.","properties":{"code":{"type":"integer","description":"Meta error code"},"subcode":{"type":"integer","description":"Meta error_subcode"},"fbtraceId":{"type":"string","description":"Meta fbtrace_id, quote this in a Meta bug report"},"type":{"type":"string","description":"Meta error type (e.g. OAuthException)"}}}}}}}}}}}},"400":{"x-summary":"The request is invalid, such as an unsupported attachment or a WhatsApp account without Direct Send, or the platform rejected the send.","description":"Bad request, e.g.:\n\n- Attachment not supported for the platform, or a validation error.\n- Category combined with a template or attachment, or used on a non-WhatsApp account.\n- The WhatsApp Business Account is not eligible for Direct Send.\n\nMeta rejections (e.g. sending outside the messaging window) and TikTok business-account rejections arrive with code platform_api_error, type platform_error, and platform + platformError set.\n","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"type":{"type":"string","description":"Present on Meta and TikTok pass-through rejections: platform_error when the platform rejected the send (see platform/platformError below), invalid_request_error for validation failures.","enum":["platform_error","invalid_request_error"]},"code":{"type":"string","description":"Stable machine-readable reason.\n\n- PLATFORM_LIMITATION: a capability the platform does not offer (e.g. Bluesky and Reddit DMs reject media).\n- MISSING_PARTICIPANT: the stored conversation has no recipient to send to.\n- DIRECT_SEND_NOT_ELIGIBLE and DIRECT_SEND_BLOCKED: the WhatsApp Business Account needs Meta to grant or restore Direct Send access.\n- DIRECT_SEND_LIMITED: temporary; Meta lifts it on its own.\n- platform_api_error: the platform itself rejected the send (see platformError).\n","enum":["PLATFORM_LIMITATION","MISSING_PARTICIPANT","INVALID_TEMPLATE_HEADER","DIRECT_SEND_NOT_ELIGIBLE","DIRECT_SEND_LIMITED","DIRECT_SEND_BLOCKED","platform_api_error"]},"platform":{"type":"string","description":"Present alongside code platform_api_error. The platform that rejected the send (e.g. instagram, facebook, whatsapp, tiktok)."},"platformError":{"type":"object","description":"Instagram, Facebook, WhatsApp, or TikTok. The platform's diagnostic fields for the rejected send or template lookup. WhatsApp lookup errors retain only code, message, and error_data.details. On TikTok only code, message, and request_id are set. Absent when the failure did not come from the platform.","properties":{"code":{"type":"integer","description":"Meta or TikTok error code"},"subcode":{"type":"integer","description":"Meta error_subcode"},"fbtraceId":{"type":"string","description":"Meta fbtrace_id, quote this in a Meta bug report"},"type":{"type":"string","description":"Meta error type (e.g. OAuthException)"},"message":{"type":"string","description":"TikTok error message"},"request_id":{"type":"string","description":"TikTok request_id, quote this in a TikTok support ticket"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/BalanceRequired"},"403":{"x-summary":"The send was refused: enable the Inbox add-on, use the locked sandbox template, and send inside the messaging window.","description":"Inbox addon required, a sandbox send with a template other than the locked sandbox template, or Meta rejected the send outside the messaging window (type platform_error, code platform_api_error, platform, platformError with code/subcode/fbtraceId/type)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"x-summary":"The same Idempotency-Key is still processing, or another app owns the thread: retry later, or take thread control and resend.","description":"Conflict. One of:\n\n- The same Idempotency-Key is still processing. Retry after a short backoff.\n- On Facebook and Instagram, another app owns the thread under Meta's handover protocol (code not_thread_owner, Meta subcode 2534037 in platformError). `details.ownerAppId` names the owner when Meta reports it.\n\nTo fix not_thread_owner, take control with POST /v1/inbox/conversations/{conversationId}/thread-control, then resend. Only accounts connected through a Facebook Page can take; an Instagram Login connection cannot.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"x-summary":"The Idempotency-Key was reused with a different request, or the audio could not be downloaded: use a new key or public URL.","description":"Idempotency-Key reused with a different request, or the audio at attachmentUrl could not be downloaded (code attachment_fetch_failed, param attachmentUrl, the upstream HTTP status in the message): the URL is private, expired or gone. Nothing was sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"x-summary":"The upstream platform quota is exhausted, or Meta rejected the template lookup, and nothing was sent: retry after the `Retry-After` delay.","description":"Rate limited. Either the connected account's upstream platform quota is exhausted (code rate_limited, see Retry-After; Reddit allows 1000 requests per 10 minutes per connected user; TikTok code 40100 also lands here with platform and platformError set), or Meta rejected the WhatsApp template-definition lookup (code platform_api_error). No message was sent.","headers":{"Retry-After":{"description":"Seconds until the upstream quota resets, when the platform reported it.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/WhatsAppTemplateLookupError"}]}}}},"500":{"x-summary":"The platform rejected or failed the send: Zernio does not retry, so retry only if your use case tolerates a duplicate message.","description":"The platform rejected or failed the send. Meta 5xx failures also arrive as a platform_error envelope (code platform_api_error, with platform and platformError set).\n\nZernio does NOT retry a send internally: a message send is not idempotent, and an opaque upstream failure (e.g. WhatsApp 131000) does not say whether the message was delivered. Retrying may deliver the message twice, so retry only if your use case tolerates a duplicate.\n"},"502":{"x-summary":"The WhatsApp account has no Business Account ID, or the platform failed upstream, and no template message was sent.","description":"The WhatsApp account has no Business Account ID, or the platform returned an upstream failure (a template with no approved variant in that language is a 400). No WhatsApp template message is sent when definition lookup fails.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/WhatsAppTemplateLookupError"}]}}}},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"},"default":{"x-summary":"Meta rejected the WhatsApp template-definition lookup with an upstream status, and no message was sent: retry later.","description":"Meta rejected the WhatsApp template-definition lookup with another upstream status. No message was sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhatsAppTemplateLookupError"}}}}}}},"/v1/whatsapp/media/{mediaId}":{"get":{"x-resource-group":"messages","operationId":"getWhatsAppMedia","tags":["WhatsApp"],"summary":"Download WhatsApp media","description":"Streams the binary for a WhatsApp attachment. This is the endpoint the `url` on a WhatsApp `attachments[]` entry points at, in both the `message.received` webhook and the List messages response.\n\n### This is an authenticated endpoint, not a public link\n\nSend `Authorization: Bearer <your API key>` exactly as you would for any other call. Passing the URL straight to a browser, an LLM vision API, or a no-code \"download file\" step without the header returns `401`.\n\nThis is the most common integration mistake on this endpoint. It differs from Instagram, Facebook and Telegram, whose `attachments[].url` is a direct CDN link that needs no header.\n\n### Fetch on receipt, not lazily\n\nWhatsApp media lives in Meta's media store, not ours, and it is removed after a limited retention window (currently 7 days, and Meta has been dropping some inbound media sooner).\n\nOnce Meta drops it the media is unrecoverable and this endpoint answers `400` permanently, so retrying will never succeed. Download and store the bytes when the webhook arrives.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"mediaId","in":"path","required":true,"schema":{"type":"string"},"description":"The media id from `attachments[].payload.id`."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The WhatsApp account that received the media."}],"responses":{"200":{"description":"The media binary, streamed with its original content type.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"x-summary":"The media expired or was deleted on WhatsApp servers: the failure is permanent, so do not retry.","description":"Media is no longer available on WhatsApp servers (expired or deleted by Meta). Permanent, do not retry."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found, not accessible to the caller, or the media does not belong to it."},"502":{"description":"Meta could not be reached or returned an unexpected error."}}}},"/v1/inbox/conversations/{conversationId}/messages/{messageId}":{"patch":{"x-resource-group":"messages","operationId":"editInboxMessage","summary":"Edit message","description":"Edit a previously sent message. Platform support:\n- Telegram: text and/or reply markup, any time\n- 'iMessage: text only, within 15 minutes of sending (Apple''s limit; 409 `edit_window_expired` after that). Group messages included. The stored message keeps its edit history.'\n- All others: returns 400\n","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"The conversation ID"},{"name":"messageId","in":"path","required":true,"schema":{"type":"string"},"description":"The platform message ID to edit (iMessage also accepts the Zernio message id)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"Account ID"},"text":{"type":"string","description":"New message text"},"replyMarkup":{"type":"object","description":"New inline keyboard markup","properties":{"type":{"type":"string","enum":["inline_keyboard"]},"keyboard":{"type":"array","items":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"callbackData":{"type":"string"},"url":{"type":"string"}}}}}}}}}}}},"responses":{"200":{"description":"Message edited","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"messageId":{"type":"integer"}}}}}}}},"400":{"description":"Not supported or invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"}}},"delete":{"x-resource-group":"messages","operationId":"deleteInboxMessage","summary":"Delete message","description":"Delete a message from a conversation. Platform support varies:\n\n- Telegram: full delete (bot's own messages anytime, others if admin)\n- X: full delete (own DM events only)\n- Bluesky: delete for self only (recipient still sees it)\n- Reddit: delete from sender's view only\n- iMessage: unsend (the bubble disappears for the recipient) within 2 minutes of sending (Apple's limit; 409 `unsend_window_expired` after that). Own outbound messages only.\n- Facebook, Instagram, WhatsApp: not supported (returns 400)\n","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"The conversation ID"},{"name":"messageId","in":"path","required":true,"schema":{"type":"string"},"description":"The platform message ID to delete"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Account ID"}],"responses":{"200":{"description":"Message deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"description":"Platform does not support deletion or invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"description":"Account or conversation not found"}}}},"/v1/inbox/conversations/{conversationId}/typing":{"post":{"x-resource-group":"messages","operationId":"sendTypingIndicator","summary":"Send typing indicator","description":"Show a typing indicator in a conversation.\n\n### Platform support\n\n- Facebook Messenger: shows \"Page is typing...\" for 20 seconds.\n- Instagram: shows \"typing...\" to the recipient (works for both Instagram Login and Facebook Login accounts). The recipient must be signed in to Instagram to see it.\n- Telegram: shows \"Bot is typing...\" for 5 seconds.\n- WhatsApp: shows \"typing...\" for up to 25 seconds. Requires a recent inbound message in the conversation (Meta references the inbound message id) and also marks that message as read as a side-effect.\n- iMessage: shows a typing bubble for ~15 seconds (1:1 conversations only; requires a recent two-way exchange).\n- All others: returns 200 but no-op (platform doesn't support it).\n\n### Response\n\nTyping indicators are best-effort. The endpoint always returns 200 even if the platform call fails.\n\n`success` reports whether a typing indicator was actually sent to the platform (`false` on unsupported platforms or when the platform call failed).\n","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"The conversation ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"Account ID"}}}}}},"responses":{"200":{"description":"Typing indicator sent (or no-op on unsupported platforms)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"description":"Account or conversation not found"}}}},"/v1/inbox/conversations/{conversationId}/thread-control":{"post":{"x-resource-group":"messages","operationId":"setConversationThreadControl","summary":"Change who answers a conversation (handover)","description":"Changes who answers a conversation, using Meta's handover protocol on WhatsApp, Facebook and Instagram.\n\n**WhatsApp**, on numbers with Meta Business Agent enabled:\n\n- `release`: hand the conversation back to the agent so it resumes answering. You must currently hold control (sending any message takes it implicitly).\n- `take`: take control before sending anything, so the agent stops replying while an operator reads the thread. Meta accepts this only from the business configured as the number's escalation partner; other apps take control by sending a message.\n- `pass`: transfer control to the number's configured escalation partner, or to the agent with `target: ai_agent`. Meta's Cloud API currently rejects it (\"Pass action is not supported\", verified 2026-09-08); use `release` to hand a thread back to the agent.\n\n**Facebook and Instagram** (Messenger Platform handover between the apps on the Page, such as Page Inbox):\n\n- `pass` with `targetAppId`: give the thread to another app (`pass_thread_control`). Page Inbox is 263902037430900.\n- `take`: take the thread back (`take_thread_control`). Meta allows it only to the Page's primary receiver, and only on accounts connected through a Facebook Page. On an Instagram Login connection it answers 400 `platform_not_supported`.\n- `request`: ask the current owner to pass the thread (`request_thread_control`); nothing changes until it does. Not available on Instagram Login connections (400 `platform_not_supported`).\n- `release`: give the thread back to the primary receiver (`release_thread_control`).\n\n### While another app owns the thread\n\nWhile another app owns a Facebook or Instagram thread, inbound messages arrive with `metadata.standby: true` and a send answers 409 `not_thread_owner`.\n\nThe conversation's `threadControl` follows the result. A `conversation.control_changed` webhook fires when Meta later reports the change.\n","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"The conversation ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","action"],"properties":{"accountId":{"type":"string","description":"Social account ID"},"action":{"type":"string","enum":["release","take","pass","request"],"description":"`request` is Facebook and Instagram only. `take` and `request` are refused with `platform_not_supported` on Instagram accounts connected with Instagram Login."},"target":{"type":"string","enum":["ai_agent"],"description":"WhatsApp only. With action pass: send control to Meta Business Agent instead of the escalation partner."},"targetAppId":{"type":"string","pattern":"^[0-9]+$","description":"Facebook and Instagram only, required with action pass: the Meta app id receiving the thread."},"metadata":{"type":"string","maxLength":2000,"description":"Free-form note forwarded verbatim to the app receiving control (its messaging_handovers webhook)."}}},"example":{"accountId":"64e1f0a9e2b5af0012ab34cd","action":"pass","targetAppId":"263902037430900","metadata":"Customer asked for a human"}}}},"responses":{"200":{"description":"Control transferred (or, for request, asked for)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"control":{"type":"object","properties":{"owner":{"type":"string","enum":["app","ai_agent","other"]},"ownerAppId":{"type":"string","description":"The app that received the thread, on a Facebook or Instagram pass."}}}}}}}},"400":{"description":"Invalid field, or take / request on an Instagram account connected with Instagram Login (code platform_not_supported)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"description":"Account or conversation not found"}}}},"/v1/inbox/conversations/{conversationId}/accept":{"post":{"x-resource-group":"messages","operationId":"acceptConversationRequest","summary":"Accept a message request","description":"Accept a Facebook or Instagram Message Request by replying to it.\n\nFacebook Page requests are listed with `GET /v1/inbox/conversations?folder=requests`; Instagram answers PLATFORM_LIMITATION there.\n\nMeta has no separate accept call: the first reply is what moves the thread into the inbox. So this sends `message` through the same path, checks and webhooks as `POST /v1/inbox/conversations/{conversationId}/messages`, and answers the same way.\n\nSupports the `Idempotency-Key` header.\n","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` of the request item from the requests folder."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","message"],"properties":{"accountId":{"type":"string","description":"Facebook or Instagram social account ID"},"message":{"type":"string","minLength":1,"description":"The reply that accepts the request"}}},"example":{"accountId":"64e1f0a9e2b5af0012ab34cd","message":"Thanks for reaching out! How can we help?"}}}},"responses":{"200":{"description":"Reply sent, the request is accepted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"messageId":{"type":"string"}}}}}}}},"400":{"description":"Invalid body, or an account that is not Facebook or Instagram (PLATFORM_NOT_SUPPORTED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required or plan limit reached"},"404":{"description":"Account or conversation not found"},"409":{"x-summary":"The same Idempotency-Key is still processing, or another app owns the thread: retry later, or take thread control first and then resend.","description":"The same Idempotency-Key is still processing, or another app owns the thread under Meta's handover protocol (code not_thread_owner, `details.ownerAppId` names it when Meta says). Take control with thread-control first (accounts connected through a Facebook Page only; an Instagram Login connection cannot take).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/inbox/labels":{"get":{"x-resource-group":"messages","operationId":"listInboxLabels","summary":"List the Page's conversation labels","description":"Facebook Messenger only. Lists the custom labels defined on the Page (Graph `/{page-id}/custom_labels`). Other platforms answer 400 `platform_not_supported`.","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Facebook social account ID"}],"responses":{"200":{"description":"The Page's labels","content":{"application/json":{"schema":{"type":"object","properties":{"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Meta label id"},"name":{"type":"string"}}}}}}}}},"400":{"x-summary":"The accountId is invalid, the account is not Facebook, or Meta permanently refused the request, so retrying does not help.","description":"Invalid accountId, or an account that is not Facebook (platform_not_supported), or Meta refusing for good (platform_api_error with Meta's error_user_title and error_user_msg in the message, e.g. the Page has not accepted the label privacy terms, subcode 2018344, in platformError). A transient Meta failure answers 502","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"description":"Account not found"},"422":{"description":"No Facebook Page is selected on this account (linked_account_required); reconnect it and select the Page"}}},"post":{"x-resource-group":"messages","operationId":"createInboxLabel","summary":"Create a conversation label","description":"Facebook Messenger only. Creates a custom label on the Page (Graph `POST /{page-id}/custom_labels`). Other platforms answer 400 `platform_not_supported`.","tags":["Messages"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","name"],"properties":{"accountId":{"type":"string","description":"Facebook social account ID"},"name":{"type":"string","minLength":1,"description":"Label name"}}},"example":{"accountId":"64e1f0a9e2b5af0012ab34cd","name":"VIP"}}}},"responses":{"201":{"description":"Label created","content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"object","properties":{"id":{"type":"string","description":"Meta label id"},"name":{"type":"string"}}}}}}}},"400":{"x-summary":"The body is invalid, the account is not Facebook, or Meta permanently refused the request, so retrying does not help.","description":"Invalid body, or an account that is not Facebook (platform_not_supported), or Meta refusing for good (platform_api_error with Meta's error_user_title and error_user_msg in the message, e.g. the Page has not accepted the label privacy terms, subcode 2018344, in platformError). A transient Meta failure answers 502","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"description":"Account not found"},"422":{"description":"No Facebook Page is selected on this account (linked_account_required); reconnect it and select the Page"}}}},"/v1/inbox/labels/{labelId}":{"delete":{"x-resource-group":"messages","operationId":"deleteInboxLabel","summary":"Delete a conversation label","description":"Facebook Messenger only. Deletes a custom label from the Page (Graph `DELETE /{label-id}`), which also removes it from every conversation. The id must be one of the Page's custom labels, otherwise 404 `resource_not_found`. Other platforms answer 400 `platform_not_supported`.","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"labelId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]+$"},"description":"Meta label id"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Facebook social account ID"}],"responses":{"200":{"description":"Label deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"x-summary":"The id is invalid, the account is not Facebook, or Meta permanently refused the request, so retrying does not help.","description":"Invalid id, or an account that is not Facebook (platform_not_supported), or Meta refusing for good (platform_api_error with Meta's error_user_title and error_user_msg in the message, e.g. the Page has not accepted the label privacy terms, subcode 2018344, in platformError). A transient Meta failure answers 502","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"description":"Account not found, or the label is not one of the Page's custom labels"},"422":{"description":"No Facebook Page is selected on this account (linked_account_required); reconnect it and select the Page"}}}},"/v1/inbox/conversations/{conversationId}/labels":{"get":{"x-resource-group":"messages","operationId":"listConversationLabels","summary":"List the labels on a conversation","description":"Facebook Messenger only. Lists the Page's custom labels applied to the person in this conversation (Graph `/{psid}/custom_labels`). Other platforms answer 400 `platform_not_supported`.","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation ID (Zernio id or Meta platform conversation id)"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Facebook social account ID"}],"responses":{"200":{"description":"The labels on the conversation's participant","content":{"application/json":{"schema":{"type":"object","properties":{"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Meta label id"},"name":{"type":"string"}}}}}}}}},"400":{"x-summary":"The accountId is invalid, the account is not Facebook, or Meta permanently refused the request, so retrying does not help.","description":"Invalid accountId, or an account that is not Facebook (platform_not_supported), or Meta refusing for good (platform_api_error with Meta's message, e.g. the Page has not accepted the label privacy terms, subcode 2018344, in platformError). A transient Meta failure answers 502","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"description":"Account or conversation not found"},"422":{"description":"No Facebook Page is selected on this account (linked_account_required); reconnect it and select the Page"}}},"post":{"x-resource-group":"messages","operationId":"addConversationLabel","summary":"Add a label to a conversation","description":"Facebook Messenger only. Applies one of the Page's custom labels to the person in this conversation (Graph `POST /{label-id}/label?user={psid}`). The id must be one of the Page's custom labels, otherwise 404 `resource_not_found`. Other platforms answer 400 `platform_not_supported`.","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation ID (Zernio id or Meta platform conversation id)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","labelId"],"properties":{"accountId":{"type":"string","description":"Facebook social account ID"},"labelId":{"type":"string","pattern":"^[0-9]+$","description":"Meta label id from listInboxLabels"}}},"example":{"accountId":"64e1f0a9e2b5af0012ab34cd","labelId":"1712444532121303"}}}},"responses":{"200":{"description":"Label added","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"x-summary":"The body is invalid, the account is not Facebook, or Meta permanently refused the request, so retrying does not help.","description":"Invalid body, or an account that is not Facebook (platform_not_supported), or Meta refusing for good (platform_api_error with Meta's message in platformError). A transient Meta failure answers 502","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"description":"Account or conversation not found, or the label is not one of the Page's custom labels"},"422":{"description":"No Facebook Page is selected on this account (linked_account_required); reconnect it and select the Page"}}}},"/v1/inbox/conversations/{conversationId}/labels/{labelId}":{"delete":{"x-resource-group":"messages","operationId":"removeConversationLabel","summary":"Remove a label from a conversation","description":"Facebook Messenger only. Removes one of the Page's custom labels from the person in this conversation (Graph `DELETE /{label-id}/label?user={psid}`). The label itself stays on the Page. The id must be one of the Page's custom labels, otherwise 404 `resource_not_found`. Other platforms answer 400 `platform_not_supported`.","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation ID (Zernio id or Meta platform conversation id)"},{"name":"labelId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]+$"},"description":"Meta label id"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Facebook social account ID"}],"responses":{"200":{"description":"Label removed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"x-summary":"The id is invalid, the account is not Facebook, or Meta permanently refused the request, so retrying does not help.","description":"Invalid id, or an account that is not Facebook (platform_not_supported), or Meta refusing for good (platform_api_error with Meta's message in platformError). A transient Meta failure answers 502","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"description":"Account or conversation not found, or the label is not one of the Page's custom labels"},"422":{"description":"No Facebook Page is selected on this account (linked_account_required); reconnect it and select the Page"}}}},"/v1/inbox/conversations/{conversationId}/read":{"post":{"x-resource-group":"messages","operationId":"markConversationRead","summary":"Mark a conversation as read","description":"Marks all unread incoming messages in the conversation as read.\n\nFor WhatsApp, this also sends read receipts (blue ticks) to the contact,\nEXCEPT on coexistence accounts (where the WhatsApp Business app on the\ncustomer's phone owns read state and we never override it).\n\nFor iMessage, this also marks the conversation read with the contact\n(1:1 conversations only). Best-effort.\n\nFor Instagram (Instagram Login and Facebook Login) and Facebook Messenger,\nthis also sends a `mark_seen` read receipt to the contact, so they see the\nconversation as seen. Best-effort: a Meta failure never fails the request.\n\nThis is the explicit, human-driven counterpart to `GET .../messages`,\nwhich is side-effect-free and does NOT mark anything read. Call this when\na user actually views the conversation.\n","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"The conversation ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"Account ID"}}}}}},"responses":{"200":{"description":"Conversation marked read","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"markedCount":{"type":"integer","description":"Number of messages marked read by this call"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"description":"Account or conversation not found"}}}},"/v1/inbox/conversations/{conversationId}/messages/{messageId}/reactions":{"post":{"x-resource-group":"messages","operationId":"addMessageReaction","summary":"Add reaction","description":"Add an emoji reaction to a message.\n\n### Platform support\n\n- Telegram: supports a subset of Unicode emoji reactions\n- WhatsApp: supports any standard emoji (one reaction per message per sender)\n- Instagram and Facebook Messenger: any standard emoji, subject to Meta's 24h messaging window\n- Slack: the emoji must have a Slack name (e.g. `:thumbsup:`); unnamed characters return 400\n- iMessage: the six Apple tapbacks (❤️ 👍 👎 😂 ‼️ ❓) render natively; any other emoji is sent as a custom emoji tapback (iOS 18+ recipients)\n- All others: returns 400 (not supported)\n","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"The conversation ID"},{"name":"messageId","in":"path","required":true,"schema":{"type":"string"},"description":"The platform message ID (as returned by GET /messages) or the Zernio message ID (as returned by the reaction webhook)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","emoji"],"properties":{"accountId":{"type":"string","description":"Account ID"},"emoji":{"type":"string","description":"Emoji character (e.g. \"👍\", \"❤️\")","example":"👍"}}}}}},"responses":{"200":{"x-summary":"The platform accepted the reaction request, but it never confirms what it acted on, so the reaction is not guaranteed.","description":"The platform accepted the reaction request. This does not guarantee the reaction was placed: the platform never confirms what it acted on.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"messageId":{"type":"string","description":"The Zernio message ID the reaction was resolved against"},"platformMessageId":{"type":"string","description":"The platform message ID the reaction was sent for"}}}}}},"400":{"description":"Platform does not support reactions or invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"description":"Account, conversation or message not found (message_not_found when messageId does not resolve to a message in this conversation)"}}},"delete":{"x-resource-group":"messages","operationId":"removeMessageReaction","summary":"Remove reaction","description":"Remove a reaction from a message.\n\n### Platform support\n\n- Telegram: send empty reaction array to clear\n- WhatsApp: send empty emoji to remove\n- Instagram and Facebook Messenger: sends Meta's `unreact` action; the emoji does not need to be repeated\n- Slack: removes the reaction we previously sent on that message\n- iMessage: retracts your existing tapback or emoji reaction on the message (400 when you have none)\n- All others: returns 400 (not supported)\n","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"The conversation ID"},{"name":"messageId","in":"path","required":true,"schema":{"type":"string"},"description":"The platform message ID (as returned by GET /messages) or the Zernio message ID (as returned by the reaction webhook)"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Account ID"}],"responses":{"200":{"x-summary":"The platform accepted the removal request but never confirms it, and the other participant's reactions stay: check `fromMe` on messages.","description":"The platform accepted the removal request. This does not guarantee a reaction was removed: the platform never confirms what it acted on, and a reaction placed by the other participant cannot be removed (platform rule). Check `fromMe` on GET /messages to know who placed a reaction.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"messageId":{"type":"string","description":"The Zernio message ID the removal was resolved against"},"platformMessageId":{"type":"string","description":"The platform message ID the removal was sent for"}}}}}},"400":{"description":"Platform does not support reactions or invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"description":"Account, conversation or message not found (message_not_found when messageId does not resolve to a message in this conversation)"}}}},"/v1/media/upload-direct":{"post":{"x-resource-group":"publishing","operationId":"uploadMediaDirect","summary":"Upload media file","description":"Upload a media file using API key authentication and get back a publicly accessible URL. The URL can be used as attachmentUrl when sending inbox messages.\n\nFiles are stored in temporary storage and auto-delete after 7 days.\n\n### Size limit\n\nThe effective maximum is about 4.5 MB. The multipart body goes through the hosting platform's request body limit, which answers 413 before the endpoint's own 25 MB check is reached.\n\nFor larger files use POST /v1/media/presign and upload straight to storage.\n\n### Compared with /v1/media/upload\n\n/v1/media/upload uses upload tokens for end-user flows. This endpoint takes your API key in the Authorization header, for programmatic use.\n","tags":["Messages"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The file to upload (about 4.5 MB at most in practice; use POST /v1/media/presign for larger files)"},"contentType":{"type":"string","description":"Override MIME type (e.g. \"image/jpeg\"). Auto-detected from file if not provided."}}}}}},"responses":{"200":{"description":"File uploaded successfully","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Publicly accessible URL for the uploaded file"},"filename":{"type":"string","description":"Generated unique filename"},"contentType":{"type":"string","description":"MIME type of the file"},"size":{"type":"integer","description":"File size in bytes"}}}}}},"400":{"description":"No file provided or file too large"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/accounts/{accountId}/messenger-menu":{"get":{"x-resource-group":"accounts","operationId":"getMessengerMenu","summary":"Get persistent menu","description":"Get the persistent menu configuration for a Facebook Messenger or Instagram account. Instagram accounts connected through Facebook Login are read through their linked Page (Meta's `platform=instagram`), Instagram Login accounts through the Instagram API.","tags":["Account Settings"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Persistent menu configuration","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Not a Facebook or Instagram account"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"put":{"x-resource-group":"accounts","operationId":"setMessengerMenu","summary":"Set persistent menu","description":"Set the persistent menu for a Facebook Messenger or Instagram account. Max 3 top-level items, max 5 nested items.\n\n- On Facebook, Meta only shows a persistent menu on a page that has a Get Started button. Set one first with PUT /v1/accounts/{accountId}/messenger-get-started.\n- A postback button whose payload is `zernio:workflow:<workflowId>` starts that workflow when tapped. The workflow must be active on this account and profile.\n","tags":["Account Settings"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["persistent_menu"],"properties":{"persistent_menu":{"type":"array","description":"Persistent menu configuration array (Meta format)","items":{"type":"object"}}}}}}},"responses":{"200":{"description":"Menu set successfully"},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"x-summary":"The page has no Get Started button: set one with the messenger-get-started endpoint, then retry.","description":"The page has no Get Started button. Set one with PUT /v1/accounts/{accountId}/messenger-get-started and retry."}}},"delete":{"x-resource-group":"accounts","operationId":"deleteMessengerMenu","description":"Removes the persistent menu from this Facebook Messenger or Instagram account.","summary":"Delete persistent menu","tags":["Account Settings"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Menu deleted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/accounts/{accountId}/messenger-get-started":{"get":{"x-resource-group":"accounts","operationId":"getMessengerGetStarted","summary":"Get FB Get Started button","description":"Get the Get Started button payload for a Facebook Messenger account. `data` is null when the page has none.","tags":["Account Settings"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Get Started button configuration","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":["object","null"],"properties":{"payload":{"type":"string","description":"Postback payload sent when a person taps Get Started"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"x-resource-group":"accounts","operationId":"setMessengerGetStarted","summary":"Set FB Get Started button","description":"Set the Get Started button shown on a Facebook page's Messenger welcome screen. Meta requires it before a persistent menu can be set.\n\nTapping it sends a postback with `payload`, which arrives as a `message.received` webhook carrying it in `metadata.postbackPayload`.\n\nUse `zernio:workflow:<workflowId>` to start a workflow on the tap; the workflow must be active on this account and profile.\n","tags":["Account Settings"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"string","minLength":1,"maxLength":1000,"description":"Postback payload sent when a person taps Get Started, e.g. `GET_STARTED` or `zernio:workflow:<workflowId>`."}}},"example":{"payload":"zernio:workflow:5190ac0343606395fce014b0"}}}},"responses":{"200":{"description":"Get Started button set","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"x-resource-group":"accounts","operationId":"deleteMessengerGetStarted","summary":"Delete FB Get Started button","description":"Remove the Get Started button. Meta refuses while a persistent menu is set, so delete the menu first.","tags":["Account Settings"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Get Started button deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"x-summary":"A persistent menu is still set: delete it with the messenger-menu endpoint first, then retry.","description":"A persistent menu is still set. Delete it with DELETE /v1/accounts/{accountId}/messenger-menu first."}}}},"/v1/accounts/{accountId}/messenger-greeting":{"get":{"x-resource-group":"accounts","operationId":"getMessengerGreeting","summary":"Get FB greeting text","description":"Get the greeting text a Facebook page shows on its Messenger welcome screen, one entry per locale. `data` is empty when the page has none.","tags":["Account Settings"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Greeting locales","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MessengerGreeting"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"x-resource-group":"accounts","operationId":"setMessengerGreeting","summary":"Set FB greeting text","description":"Set the greeting text on a Facebook page's Messenger welcome screen (Meta's `greeting` Messenger Profile field). One entry must use locale `default`; add more for other locales. Meta personalises `{{user_first_name}}`, `{{user_last_name}}` and `{{user_full_name}}`. Replaces every locale already set.","tags":["Account Settings"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["greeting"],"properties":{"greeting":{"type":"array","minItems":1,"description":"One entry per locale; one must use locale `default`.","items":{"$ref":"#/components/schemas/MessengerGreeting"}}}},"example":{"greeting":[{"locale":"default","text":"Hi {{user_first_name}}, how can we help?"},{"locale":"es_ES","text":"Hola {{user_first_name}}, en que te ayudamos?"}]}}}},"responses":{"200":{"description":"Greeting set","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"x-resource-group":"accounts","operationId":"deleteMessengerGreeting","summary":"Delete FB greeting text","description":"Remove the greeting text from every locale.","tags":["Account Settings"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Greeting deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/accounts/{accountId}/messenger-ice-breakers":{"get":{"x-resource-group":"accounts","operationId":"getMessengerIceBreakers","summary":"Get FB ice breakers","description":"Get the ice breakers (FAQ questions shown when a person opens a new Messenger thread) for a Facebook page, one entry per locale. Instagram ice breakers live at /v1/accounts/{accountId}/instagram-ice-breakers.","tags":["Account Settings"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ice breakers per locale","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MessengerIceBreakerLocale"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"x-resource-group":"accounts","operationId":"setMessengerIceBreakers","summary":"Set FB ice breakers","description":"Set up to 4 ice breakers per locale for a Facebook page (Meta's `ice_breakers` Messenger Profile field). Replaces every locale already set.\n\n- One entry must use locale `default`.\n- A tap sends a postback with the question's `payload`, which arrives as `message.received` with `metadata.postbackPayload`.\n- Use `zernio:workflow:<workflowId>` to start a workflow (it must be active on this account and profile).\n","tags":["Account Settings"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ice_breakers"],"properties":{"ice_breakers":{"type":"array","minItems":1,"description":"One entry per locale; one must use locale `default`.","items":{"$ref":"#/components/schemas/MessengerIceBreakerLocale"}}}},"example":{"ice_breakers":[{"locale":"default","call_to_actions":[{"question":"Book a table","payload":"zernio:workflow:5190ac0343606395fce014b0"},{"question":"Opening hours","payload":"HOURS"}]}]}}}},"responses":{"200":{"description":"Ice breakers set","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"x-resource-group":"accounts","operationId":"deleteMessengerIceBreakers","summary":"Delete FB ice breakers","description":"Remove the ice breakers from every locale.","tags":["Account Settings"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ice breakers deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/accounts/{accountId}/instagram-ice-breakers":{"get":{"x-resource-group":"accounts","operationId":"getInstagramIceBreakers","summary":"Get IG ice breakers","description":"Get the ice breaker configuration for an Instagram account.","tags":["Account Settings"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ice breaker configuration","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Not an Instagram account"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"put":{"x-resource-group":"accounts","operationId":"setInstagramIceBreakers","summary":"Set IG ice breakers","description":"Set ice breakers for an Instagram account. Max 4 ice breakers, question max 80 chars.","tags":["Account Settings"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ice_breakers"],"properties":{"ice_breakers":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"object","required":["question","payload"],"properties":{"question":{"type":"string","minLength":1,"maxLength":80},"payload":{"type":"string","minLength":1}}}}}}}}},"responses":{"200":{"description":"Ice breakers set successfully"},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"delete":{"x-resource-group":"accounts","operationId":"deleteInstagramIceBreakers","description":"Removes the ice breaker questions from an Instagram account's Messenger experience.","summary":"Delete IG ice breakers","tags":["Account Settings"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ice breakers deleted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/accounts/{accountId}/telegram-commands":{"get":{"x-resource-group":"accounts","operationId":"getTelegramCommands","summary":"Get TG bot commands","description":"Get the bot commands configuration for a Telegram account.","tags":["Account Settings"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Bot commands list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"command":{"type":"string","minLength":1,"maxLength":32,"pattern":"^[a-z0-9_]+$"},"description":{"type":"string","minLength":1,"maxLength":256}}}}}}}}},"400":{"description":"Not a Telegram account"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"put":{"x-resource-group":"accounts","operationId":"setTelegramCommands","summary":"Set TG bot commands","description":"Set bot commands for a Telegram account.","tags":["Account Settings"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["commands"],"properties":{"commands":{"type":"array","maxItems":100,"items":{"type":"object","required":["command","description"],"properties":{"command":{"type":"string","minLength":1,"maxLength":32,"pattern":"^[a-z0-9_]+$","description":"Bot command without leading slash"},"description":{"type":"string","minLength":1,"maxLength":256,"description":"Command description"}}}}}}}}},"responses":{"200":{"description":"Commands set successfully"},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"delete":{"x-resource-group":"accounts","operationId":"deleteTelegramCommands","description":"Clears all bot commands configured for a Telegram bot account.","summary":"Delete TG bot commands","tags":["Account Settings"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Commands deleted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}":{"get":{"x-resource-group":"messages","operationId":"getMessageAttachment","summary":"Resolve message attachment","description":"Resolve one attachment on a message to a media url that works right now.\n\n### Why it exists\n\nInstagram and Facebook sign DM media urls per request and expire them. So the `url` on a message is a snapshot: it works when you read the message and stops working later.\n\nThis endpoint checks the stored url and, when it has gone stale, re-mints the message's media from Meta and persists it before answering.\n\nThe message id never expires, so this URL is the one to store. It is returned ready-made on each attachment as `refreshUrl` when you read a message over REST.\n\n### Building the URL from a webhook\n\n**Webhook payloads do not carry `refreshUrl`**, so a webhook-driven integration builds this URL itself. Every piece is in the event:\n\n- `message.conversationId`\n- `message.platformMessageId`\n- the attachment's zero-based position\n- `account.accountId`\n\n**`accountId` is a required query parameter**. Omitting it returns `400` `missing_required_field`, which is the same requirement `GET /v1/whatsapp/media/{mediaId}` has.\n\n### Response format\n\n- By default it responds `302` to the live media url, so it can be used directly as an `<img src>` on a browser session.\n- API-key integrators should pass `?format=json` and read `url` off the body, since a browser cannot attach an Authorization header to an image request.\n\n### Other platforms\n\nOnly Instagram and Facebook media can be re-minted. On other platforms the stored url is returned as-is when it still resolves, and `404` otherwise.\n","tags":["Messages"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"The conversation ID (Zernio id or platform conversation id)"},{"name":"messageId","in":"path","required":true,"schema":{"type":"string"},"description":"The message id as returned by the list-messages endpoint (the platform message id)"},{"name":"index","in":"path","required":true,"schema":{"type":"integer","minimum":0},"description":"Zero-based position of the attachment in the message's attachments array"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Account ID. Required: without it the request returns 400 missing_required_field."},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["redirect","json"],"default":"redirect"},"description":"`redirect` (default) answers 302 to the media; `json` returns the url in the body"}],"responses":{"200":{"description":"Resolved url (only when format=json)","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"url":{"type":"string","description":"Live media url. Short-lived; re-request this endpoint rather than storing it."},"refreshed":{"type":"boolean","description":"True when the stored url had expired and was re-minted from the platform."}}}}}},"302":{"description":"Redirect to the live media url"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"description":"Account, conversation, message or attachment not found, or the platform no longer serves the media"}}}},"/v1/inbox/comments":{"get":{"x-resource-group":"engagement","operationId":"listInboxComments","summary":"List commented posts","description":"Returns posts with comment counts from all connected accounts. Aggregates data across multiple accounts.\n\n### Caching\n\nResponses are cached for up to 10 minutes, so the feed may lag new comments by that window.\n\nDo not poll this endpoint for real-time updates. Subscribe to the `comment.received` webhook, which fires for every new comment across your posts and carries the post reference needed to keep this list current.\n\n### Meta ads\n\nFor users with the Ads add-on (accounts on usage-based billing always qualify), the user's Meta ads (boosted/dark posts) are included too.\n\nThere's one row per (ad, placement-with-comments). An ad that runs on both Facebook feed and Instagram feed produces up to two rows, since the Page dark post and the IG media have separate comment threads.\n\nEach ad row is flagged `isAd: true` with `adId` and `placement` (`id` is `{adId}:{placement}`). Filter with `platform`:\n\n- `?platform=metaads`: *only* ad rows.\n- `facebook`/`instagram`: *organic* posts only (no ads).\n- Omitted: both.\n\nFetch a row's thread from GET /v1/ads/{adId}/comments?placement={placement}.\n\nAd comment counts are read with the Marketing API token (Facebook side) or the connected Instagram account's token (Instagram side). A row whose count can't be read is omitted.\n\n### Pagination\n\nPagination walks each account's platform listing. Following `nextCursor` reaches past the first page on Facebook, Instagram, Threads, LinkedIn and YouTube, the platforms that support a server-side date window. On the others the listing stops at its first page.\n\nCursor pagination is only coherent for the default sort (`sortBy=date`, `sortOrder=desc`). With `sortOrder=asc`, or with `sortBy=comments`, the cursor filter does not match the sort order and the second page is unreliable.\n\n`minComments` is applied to each page after pagination. A page can hold fewer than `limit` posts, even none, while `hasMore` is true; keep following `nextCursor`.\n\n`nextCursor` is opaque: pass it back verbatim, never construct or parse it, its composition may change without notice. Because each page re-queries a live window, results can still shift between requests, so dedupe by `id` on the client.\n\n### Comment counts\n\n`commentCount` semantics differ by platform:\n\n- YouTube's includes replies.\n- Facebook's counts top-level comments only.\n","tags":["Comments"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Filter by profile ID"},{"name":"platform","in":"query","schema":{"type":"string","enum":["facebook","instagram","twitter","bluesky","threads","youtube","linkedin","reddit","tiktok","metaads"]},"description":"Filter by platform. `metaads` is a synthetic value meaning the user's ads (boosted/dark posts) only; `facebook`/`instagram` return organic posts only. `tiktok` covers accounts connected through the TikTok Business app only; developer-app TikTok accounts are returned under `meta.accountsSkipped`."},{"name":"minComments","in":"query","schema":{"type":"integer","minimum":0},"description":"Minimum comment count, applied to each page after pagination"},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Posts created after this date"},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["date","comments"],"default":"date"},"description":"Sort field"},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort order"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Filter by specific account ID.\n\nWith `platform=metaads` it takes the Meta Ads account ID, or the Facebook or Instagram account ID the Meta Ads connection belongs to, which returns that connection's ad rows.\n\nA Facebook or Instagram account with no Meta Ads connection returns no rows. An account on any other platform returns 400.\n"}],"responses":{"200":{"description":"Aggregated posts with comments","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"platform":{"type":"string"},"accountId":{"type":"string"},"accountUsername":{"type":"string"},"content":{"type":"string","description":"The post text/caption. On ad rows (isAd: true) this is the AD NAME, not the underlying post's caption. The creative text isn't exposed here."},"picture":{"type":["string","null"],"description":"Post media thumbnail. On ad rows this is the ad creative thumbnail."},"permalink":{"type":["string","null"],"description":"Public URL of the post. On ad rows: the Facebook dark-post URL (facebook placement) or the IG media permalink (instagram placement); may be null when unknown."},"createdTime":{"type":"string","format":"date-time"},"commentCount":{"type":"integer"},"likeCount":{"type":"integer","description":"Not fetched for ad rows (always 0 there)."},"cid":{"type":["string","null"],"description":"Bluesky content identifier"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name"},"isAd":{"type":"boolean","description":"True when this row is an ad (boosted/dark post). `platform` is then the placement (facebook = the Page dark post / instagram = the IG media), `id` is `{adId}:{placement}`, and the thread is at GET /v1/ads/{adId}/comments?placement={placement}."},"adId":{"type":"string","description":"Internal Zernio ad id, only on ad rows."},"placement":{"type":"string","enum":["facebook","instagram"],"description":"Which side of the ad this row's comments are on, only on ad rows."}}}},"pagination":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}},"meta":{"type":"object","properties":{"accountsQueried":{"type":"integer"},"accountsFailed":{"type":"integer"},"failedAccounts":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string"},"accountUsername":{"type":["string","null"]},"platform":{"type":"string"},"error":{"type":"string"},"code":{"type":["string","null"],"description":"Error code if available (e.g. TOKEN_EXPIRED, or X_INBOX_NOT_ENABLED for an X account whose owner has not enabled X inbox)"},"retryAfter":{"type":["integer","null"],"description":"Seconds to wait before retry (rate limits)"}}}},"lastUpdated":{"type":"string","format":"date-time"},"accountsSkipped":{"type":"array","description":"Connected accounts that were not queried: their platform does not support this feature, or the account is not enabled for it","items":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string"}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"}}}},"/v1/inbox/comments/{postId}":{"get":{"x-resource-group":"engagement","operationId":"getInboxPostComments","summary":"Get post comments","description":"Fetch comments for a specific post. Requires accountId query parameter.\n\n### Replies to a comment\n\nPass `commentId` (Facebook, Instagram, Reddit, TikTok) to fetch replies to a specific comment instead of the post's top-level comments.\n\n- Facebook, Instagram and TikTok return the comment's replies, paged by `limit`/`cursor`.\n- Reddit returns the focused comment thread instead.\n- On Facebook and Instagram the requested comment itself comes back in the top-level `comment` field.\n\nOn Facebook, passing a COMMENT id as `postId` (instead of using `commentId`) is also supported for backwards compatibility. It returns that comment's replies the same way.\n\nPrefer `commentId` for new integrations; it also works on Instagram, which rejects a comment id passed as `postId`. YouTube does not support either form: `postId` must be a video id.\n\n### Caching\n\nResponses are cached for up to 10 minutes, so a page may lag new comments by that window.\n\nDo not poll this endpoint for real-time updates: subscribe to the `comment.received` webhook, which delivers new comments as they arrive. Your own writes (creating, replying to, or deleting a comment) refresh the cache immediately.\n\n### TikTok\n\nTikTok is served for accounts connected through the TikTok for Business app:\n\n- `postId` is the TikTok video id.\n- Each top-level comment carries up to three inline replies.\n- `commentId` pages the full reply list of one comment.\n\nDeveloper-app TikTok accounts return 400 with code `PLATFORM_LIMITATION`.\n\n### X (Twitter)\n\nWhen `postId` is itself a reply rather than the thread's root post, only replies to that specific post are returned, not the whole conversation thread.\n\n### Hidden comments\n\n- Facebook Pages and Instagram accounts connected through Instagram Login return them with `isHidden: true`.\n- Instagram accounts connected through Facebook Login do not return them at all (Meta omits them, together with their replies). So a hidden comment and a deleted one look the same on this read.\n","tags":["Comments"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"postId","in":"path","required":true,"description":"Zernio post ID or platform-specific post ID. Zernio IDs are auto-resolved.\n\n- **LinkedIn:** pass the post id exactly as the feed returns it (urn:li:share:<id> or urn:li:ugcPost:<id>). A bare number is read as an activity id (urn:li:activity:<n>, the number in a linkedin.com/feed/update URL), so a share or ugcPost number passed bare returns an empty list.\n- **Facebook:** a comment ID is also accepted and returns that comment's replies (kept for backwards compatibility). Prefer the `commentId` query parameter, which also works on Instagram.\n","schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"subreddit","in":"query","schema":{"type":"string"},"description":"(Reddit only) Subreddit name"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum number of comments to return"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor, returned by a previous call as `pagination.cursor`. This is the platform's own opaque paging value passed through verbatim: never construct, decode or validate it client-side."},{"name":"commentId","in":"query","schema":{"type":"string"},"description":"(Facebook, Instagram, Reddit and TikTok) Get replies to a specific comment. On Facebook and Instagram, the requested comment is returned in the top-level `comment` field and comments[] holds its replies."}],"responses":{"200":{"description":"Comments for the post","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"message":{"type":"string"},"createdTime":{"type":"string","format":"date-time"},"from":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"username":{"type":"string"},"picture":{"type":["string","null"]},"isOwner":{"type":"boolean"},"verifiedType":{"type":["string","null"],"enum":["blue","government","business","none"],"description":"X verified badge type. Only present for X comments."}}},"likeCount":{"type":"integer"},"replyCount":{"type":"integer","description":"The platform's own reply count, which includes hidden and deleted replies. Can exceed replies[].length even when repliesHasMore is false or absent."},"platform":{"type":"string","description":"The platform this comment is from"},"url":{"type":["string","null"],"description":"Direct link to the comment on the platform (if available)"},"replies":{"type":"array","items":{"type":"object"}},"repliesHasMore":{"type":"boolean","description":"Facebook only. True when replies[] (capped at 10) does not hold the comment's full reply thread.\n\nFetch the rest by passing the comment id as the `commentId` query parameter to GET /v1/inbox/comments/{postId} (or, for backwards compatibility, as `postId`).\n\nAbsent (not false) on every other platform, including Instagram, which has no equivalent signal.\n"},"canReply":{"type":"boolean","description":"Whether this comment can be replied to. Always present."},"canDelete":{"type":"boolean","description":"Whether DELETE is expected to work on this comment. True for the account's own comments, and for anyone's comment on Facebook, Instagram, YouTube and LinkedIn organization accounts. On TikTok, TikTok's own flag decides. False does not block the call: the platform decides. Always present."},"canHide":{"type":"boolean","description":"Whether hide is supported for this comment's platform (Facebook, Instagram, Threads, X, TikTok). It does not check each comment: X needs a conversation started by the account, and Threads only hides top-level replies. Always present."},"canLike":{"type":"boolean","description":"Whether this comment can be liked (Facebook, X, Bluesky, Reddit, LinkedIn, TikTok). Always present."},"isHidden":{"type":"boolean","description":"Whether the comment is currently hidden. On Instagram accounts connected through Facebook Login, Meta leaves hidden comments (and their replies) out of the list entirely, so they never appear with isHidden true; Instagram Login accounts and Facebook Pages return them with isHidden true."},"isLiked":{"type":"boolean","description":"Whether the current user has liked this comment"},"attachment":{"allOf":[{"$ref":"#/components/schemas/CommentAttachment"}],"description":"The comment's media, whenever the platform returns one (replies included). Supported on Facebook, TikTok, X, Threads and Bluesky; absent when the comment has no media and on every other platform. See CommentAttachment for each platform's `type` values."},"likeUri":{"type":["string","null"],"description":"Bluesky like URI for unliking"},"cid":{"type":["string","null"],"description":"Bluesky content identifier"},"parentId":{"type":["string","null"],"description":"ID of the parent comment.\n\n- Facebook and Instagram: present on entries inside replies[]; omitted on top-level entries.\n- X: present inside replies[] and on top-level entries, where it holds the ID of the post replied to.\n- Every other platform: omitted; the parent relationship is expressed only through replies[] nesting.\n\nWhen omitted, the key is absent, not null."},"rootUri":{"type":["string","null"],"description":"Bluesky root post URI"},"rootCid":{"type":["string","null"],"description":"Bluesky root post CID"}}}},"post":{"description":"(Reddit, Facebook and Instagram) Metadata for the target post, returned with the comments so you can render a preview without another request.\n\n**Facebook and Instagram** return the Meta shape: post thumbnail, text and permalink, for any post the account can read, including hidden dark posts Meta publishes per ad variant (dynamic creative, placement asset customization, Advantage+).\n\n- Facebook posts need the Facebook Page connection; Instagram media the Instagram connection.\n- `thumbnailUrl` and `mediaUrl` are expiring Meta CDN URLs: store a copy to render them later.\n- On Instagram, `productType` tells an ad (`AD`) from organic media (`FEED`, `REELS`, `STORY`).\n\n**Absent** on other platforms, when the connection's token cannot read the post, and on Reddit when the upstream response lacks the post listing (deleted post, malformed response).\n","anyOf":[{"title":"Reddit post","type":"object","properties":{"id":{"type":"string","description":"Reddit post base36 id (e.g. \"1tjtj26\")"},"fullname":{"type":"string","description":"Fullname with type prefix (e.g. \"t3_1tjtj26\")"},"title":{"type":"string"},"selftext":{"type":"string","description":"Body text for self-posts (empty for link posts)"},"author":{"type":"string","description":"Reddit username, without the u/ prefix"},"subreddit":{"type":"string","description":"Subreddit name, without the r/ prefix"},"permalink":{"type":"string","description":"Absolute URL to the post on reddit.com"},"url":{"type":"string","description":"For link posts, the external URL; for self-posts, the Reddit permalink"},"score":{"type":"integer","description":"Net upvotes (upvotes minus downvotes)"},"numComments":{"type":"integer"},"createdUtc":{"type":"integer","description":"Unix timestamp in seconds"},"over18":{"type":"boolean"},"stickied":{"type":"boolean"},"flairText":{"type":["string","null"],"description":"Link flair text if any"},"isGallery":{"type":"boolean","description":"True if the post is a Reddit gallery (multiple images)"}}},{"title":"Facebook or Instagram post","type":"object","required":["id","permalink","text","thumbnailUrl","mediaUrl","mediaType","productType","createdAt"],"properties":{"id":{"type":"string","description":"Facebook post id ({pageId}_{postId}) or Instagram media id"},"permalink":{"type":["string","null"],"format":"uri"},"text":{"type":["string","null"],"description":"Facebook post message or Instagram caption"},"thumbnailUrl":{"type":["string","null"],"format":"uri","description":"Facebook `full_picture` (or the first attachment image); Instagram `thumbnail_url` for videos, `media_url` for images. Expiring Meta CDN URL."},"mediaUrl":{"type":["string","null"],"format":"uri","description":"Instagram `media_url` (the video file for videos). Always null on Facebook. Expiring Meta CDN URL."},"mediaType":{"type":["string","null"],"description":"Instagram `media_type` (IMAGE, VIDEO, CAROUSEL_ALBUM) or the Facebook attachment type (photo, video_inline, link, ...)"},"productType":{"type":["string","null"],"description":"Instagram `media_product_type`: AD, FEED, REELS or STORY. Always null on Facebook."},"createdAt":{"type":["string","null"],"description":"Creation time as Meta returns it (e.g. 2026-05-27T17:15:51+0000)"}}},{"type":"null"}]},"comment":{"type":"object","description":"(Facebook and Instagram only) Present when `commentId` was passed: the requested\ncomment itself, in the same shape as an entry in comments[]. comments[] then holds\nthat comment's replies instead of the post's top-level comments.\n"},"pagination":{"type":"object","properties":{"hasMore":{"type":"boolean"},"cursor":{"type":["string","null"],"description":"Only present when hasMore is true. Absent on the last page, so treat its absence as the end of the thread."}}},"meta":{"type":"object","properties":{"platform":{"type":"string"},"postId":{"type":"string"},"accountId":{"type":"string"},"subreddit":{"type":["string","null"],"description":"(Reddit only) Subreddit name"},"postUrn":{"type":"string","description":"(LinkedIn only) The post URN that was queried, after a bare number is read as urn:li:activity:<n>"},"lastUpdated":{"type":"string","format":"date-time"},"adComments":{"type":["object","null"],"description":"(Facebook/Instagram only) Present when this post has no organic comments but is a boosted post: the engagement lives on the ad. Use the ad-comments endpoint instead.","properties":{"adId":{"type":"string","description":"Internal Zernio ad ID"},"adCommentsUrl":{"type":"string","description":"Path to fetch the ad's comments (GET /v1/ads/{adId}/comments)"}}}}}}}}}},"400":{"x-summary":"The request is invalid, the postId is an ad ID, or the platform rejected it: fix the request or use ad comments.","description":"Invalid request. Also returned when:\n\n- the postId belongs to a Meta ad creative / ad ID rather than an organic post (code USE_AD_COMMENTS_ENDPOINT; the response includes `adId` and `adCommentsUrl`);\n- the upstream platform rejected the request (type platform_error, code platform_api_error; the provider's payload is in platformError).\n\nMeta returns code 100 with error_subcode 33 both for a story past its 24h life and for a deleted post, so the two cannot be told apart from the response.\n"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The Inbox addon is required, or the connected account is not permitted to read this post on the platform.","description":"Inbox addon required, or the connected account is not permitted to read this post on the platform (code platform_api_error, type platform_error)"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"description":"Upstream platform error (code platform_api_error, type platform_error)"}}},"post":{"x-resource-group":"engagement","operationId":"replyToInboxPost","summary":"Reply to comment","description":"Post a reply to a post or specific comment. Requires accountId in request body.\n\n### Idempotency\n\nSend an `Idempotency-Key` header to make retries safe (e.g. after a client-side timeout where delivery is unknown).\n\n- Same key + same body replays the original response (with `Idempotent-Replayed: true`) instead of posting the comment a second time.\n- Same key + different body returns 422.\n- A key still in flight returns 409.\n\nKeys are retained for 24 hours and are scoped to the credential and to this exact path. Reusing a key against a different postId returns 422 rather than replaying the other post's response.\n\nOnly successful (2xx) responses are stored for replay. If the request throws or returns a non-2xx status the key is released, so the header protects the \"request succeeded but the response was lost\" case.\n\nAfter an ambiguous failure (a 5xx or a network timeout), list the post's comments before retrying with the same key. Treat an empty result as inconclusive rather than as proof nothing was posted.\n","tags":["Comments"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"postId","in":"path","required":true,"description":"Zernio post ID or platform-specific post ID. On LinkedIn, pass the post id exactly as the feed returns it (urn:li:share:<id> or urn:li:ugcPost:<id>); a bare number is read as an activity id (urn:li:activity:<n>).","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","message"],"properties":{"accountId":{"type":"string"},"message":{"type":"string","description":"Reply text. On LinkedIn, mention with @[https://www.linkedin.com/in/vanity] (resolved to LinkedIn's live name, same rules and errors as post content) or @[Name](urn:li:person|organization:ID); a hand-written name must match LinkedIn's exactly or it renders as plain text."},"attachmentUrl":{"type":"string","format":"uri","description":"(Facebook only) URL of an image to attach, publishing a photo comment alongside the text. The URL must be publicly accessible so Meta can fetch it. Returns 400 for other platforms."},"commentId":{"type":"string","description":"Reply to specific comment (optional)"},"parentCid":{"type":"string","description":"(Bluesky only) Parent content identifier"},"rootUri":{"type":"string","description":"(Bluesky only) Root post URI"},"rootCid":{"type":"string","description":"(Bluesky only) Root post CID"}}}}}},"responses":{"200":{"description":"Reply posted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"commentId":{"type":"string"},"isReply":{"type":"boolean"},"cid":{"type":["string","null"],"description":"Bluesky CID"}}}}}}}},"400":{"x-summary":"The request is invalid, for example an attachment URL on a non-Facebook platform or a LinkedIn mention that cannot be resolved.","description":"Invalid request (e.g. attachmentUrl on a platform other than Facebook, code PLATFORM_NOT_SUPPORTED). On LinkedIn, a profile or company URL mention that cannot be resolved returns code `linkedin_mentions_invalid`, or `linkedin_mentions_limit_exceeded` for more than 10, with `details.mentions[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"object","properties":{"mentions":{"type":"array","items":{"$ref":"#/components/schemas/LinkedInMentionIssue"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The Inbox addon is required, or the connected account is not permitted to comment on this post on the platform.","description":"Inbox addon required, or the connected account is not permitted to comment on this post on the platform (code platform_api_error, type platform_error)"},"409":{"$ref":"#/components/responses/IdempotencyKeyInFlight"},"422":{"x-summary":"The Idempotency-Key was reused with a different request, or the platform rejected the comment, for example a locked thread: check both.","description":"Idempotency-Key reused with a different request, or the platform rejected the comment (for example a locked thread, a deleted parent or a post too old for comments; code platform_api_error)"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"description":"Upstream platform error (code platform_api_error, type platform_error)"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}},"delete":{"x-resource-group":"engagement","operationId":"deleteInboxComment","summary":"Delete comment","description":"Delete a comment on a post. Supported by Facebook, Instagram, Threads, LinkedIn, Reddit, Bluesky, X (Twitter), YouTube, and TikTok (accounts connected through the TikTok for Business app). Not supported on Google Business (reviews only).\nRequires accountId and commentId query parameters.\n\nZernio does not check `canDelete` before calling the platform. When the platform refuses, the call fails with the platform's message, normally as `platform_api_error` with the platform's own 4xx status.\n\nOn Facebook, Instagram and LinkedIn organization accounts, the account can delete anyone's comment on its own posts. On Threads, Meta refuses deleting other people's replies; hide them instead. On TikTok only the account's own comments can be deleted; hide the others.\n\nOn YouTube, a comment the channel did not write is rejected instead, through the same moderation status as `setCommentModeration`, and the response still reports it as deleted. Use `setCommentModeration` directly to reverse the rejection later or to ban the author.\n","tags":["Comments"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"postId","in":"path","required":true,"description":"Zernio post ID or platform-specific post ID. On LinkedIn, pass the post id exactly as the feed returns it (urn:li:share:<id> or urn:li:ugcPost:<id>); a bare number is read as an activity id (urn:li:activity:<n>).","schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"commentId","in":"query","required":true,"description":"For LinkedIn, accepts either the numeric comment ID or the composite comment URN returned by the comments listing (e.g. urn:li:comment:(threadUrn,id))","schema":{"type":"string"}}],"responses":{"200":{"description":"Comment deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"message":{"type":"string"}}}}}}}},"400":{"description":"Platform rejected the operation (e.g., comment already deleted)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The Inbox addon is required, or the connected account is not permitted to delete this comment on the platform.","description":"Inbox addon required, or the connected account is not permitted to delete this comment on the platform (code platform_api_error, type platform_error)"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"description":"Upstream platform error (code platform_api_error, type platform_error)"}}}},"/v1/inbox/comments/{postId}/{commentId}":{"patch":{"x-resource-group":"engagement","operationId":"editInboxComment","summary":"Edit comment","description":"Edit the body of a comment the connected account posted. Supported on Reddit only.\n\nReddit keeps the same comment id after an edit. Reddit exposes no API to edit a post\ntitle, and a link post has no editable body. To edit a published post's body, use\n`POST /v1/posts/{postId}/edit`.\n","tags":["Comments"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"}},{"name":"commentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","platform","content"],"properties":{"accountId":{"type":"string","description":"The account ID"},"platform":{"type":"string","enum":["reddit"],"description":"Only Reddit supports editing a comment"},"content":{"type":"string","minLength":1,"description":"The new comment body"}}},"example":{"accountId":"60f7a1b2c3d4e5f6a7b8c9d0","platform":"reddit","content":"Edited: corrected the version number."}}}},"responses":{"200":{"description":"Comment edited","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"commentId":{"type":"string"},"platform":{"type":"string"}}},"example":{"status":"success","commentId":"t1_xyz789","platform":"reddit"}}}},"400":{"description":"Platform does not support editing comments (code: platform_not_supported), or content missing."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"description":"Account not found"},"502":{"x-summary":"Reddit was unreachable or returned an unclassified error: retry later, and note that Reddit 4xx statuses pass through unchanged.","description":"Reddit was unreachable or returned an unclassified error. Reddit 4xx statuses are forwarded as-is."}}}},"/v1/inbox/comments/{postId}/{commentId}/moderation":{"post":{"x-resource-group":"engagement","operationId":"setCommentModeration","summary":"Set comment moderation status","description":"Set a comment's moderation status. Supported on YouTube only.\n\nUse this to work a moderation queue: approve a held comment (`published`), reject it\n(`rejected`), or send it back for review (`heldForReview`).\n\nThe request must be authorized by the owner of the channel or video the comment\nbelongs to. You cannot moderate comments on videos you do not own.\n\nThis is distinct from `POST /v1/inbox/comments/{postId}/{commentId}/hide`, which\ncovers Facebook, Instagram, Threads, and X and does not apply to YouTube.\n","tags":["Comments"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"}},{"name":"commentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","platform","moderationStatus"],"properties":{"accountId":{"type":"string","description":"The account ID"},"platform":{"type":"string","enum":["youtube"],"description":"Only YouTube supports comment moderation"},"moderationStatus":{"type":"string","enum":["published","rejected","heldForReview"],"description":"published approves the comment, rejected removes it, heldForReview returns it to the queue."},"banAuthor":{"type":"boolean","description":"Also ban the comment's author, auto-rejecting their future comments. Only valid when moderationStatus is \"rejected\"; any other pairing is a 400.\n"}}},"example":{"accountId":"60f7a1b2c3d4e5f6a7b8c9d0","platform":"youtube","moderationStatus":"rejected","banAuthor":true}}}},"responses":{"200":{"description":"Moderation status applied","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"400":{"description":"Platform does not support comment moderation (code: platform_not_supported), or banAuthor was set without moderationStatus=rejected."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"description":"Account not found"},"502":{"x-summary":"YouTube rejected the request, for example because the account does not own the video: check the account and video.","description":"YouTube rejected the request (e.g. the account does not own the video)."}}}},"/v1/inbox/comments/{postId}/{commentId}/hide":{"post":{"x-resource-group":"engagement","operationId":"hideInboxComment","summary":"Hide comment","description":"Hide a comment on a post. Supported by Facebook, Instagram, Threads, X, and TikTok\n(accounts connected through the TikTok for Business app).\nHidden comments are only visible to the commenter and page admin.\n\nFor X, the reply must belong to a conversation started by the authenticated user.\n\nOn Threads only top-level replies can be hidden, and hiding one also hides its nested replies.\n","tags":["Comments"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"}},{"name":"commentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"The account ID"}}}}}},"responses":{"200":{"description":"Comment hidden","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"commentId":{"type":"string"},"hidden":{"type":"boolean"},"platform":{"type":"string"}}}}}},"400":{"x-summary":"The platform does not support hiding comments, or it rejected the call, for example because the comment is gone: check the comment.","description":"Platform does not support hiding comments (code PLATFORM_LIMITATION), or the platform rejected the call (code PLATFORM_API_ERROR with the upstream status, for example a comment that no longer exists; the platform's own error code and subcode are in platformError)."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"}}},"delete":{"x-resource-group":"engagement","operationId":"unhideInboxComment","summary":"Unhide comment","description":"Unhide a previously hidden comment. Supported by Facebook, Instagram, Threads, X, and\nTikTok (accounts connected through the TikTok for Business app).\n","tags":["Comments"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"}},{"name":"commentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Comment unhidden","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"commentId":{"type":"string"},"hidden":{"type":"boolean"},"platform":{"type":"string"}}}}}},"400":{"x-summary":"The platform does not support unhiding comments, or it rejected the call, for example because the comment is gone: check the comment.","description":"Platform does not support unhiding comments (code PLATFORM_LIMITATION), or the platform rejected the call (code PLATFORM_API_ERROR with the upstream status, for example a comment that no longer exists; the platform's own error code and subcode are in platformError)."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"}}}},"/v1/inbox/comments/{postId}/{commentId}/pin":{"post":{"x-resource-group":"engagement","operationId":"pinInboxComment","summary":"Pin comment","description":"Pin a top-level comment to the top of a post's comment section. TikTok accounts\nconnected through the TikTok for Business app only; every other platform returns 400.\n","tags":["Comments"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"}},{"name":"commentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"The social account ID"}}}}}},"responses":{"200":{"description":"Comment pinned","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"commentId":{"type":"string"},"pinned":{"type":"boolean"},"platform":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"}}},"delete":{"x-resource-group":"engagement","operationId":"unpinInboxComment","summary":"Unpin comment","description":"Unpin a previously pinned comment. TikTok accounts connected through the TikTok for\nBusiness app only.\n","tags":["Comments"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"}},{"name":"commentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Comment unpinned","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"commentId":{"type":"string"},"pinned":{"type":"boolean"},"platform":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"}}}},"/v1/inbox/comments/{postId}/{commentId}/like":{"post":{"x-resource-group":"engagement","operationId":"likeInboxComment","summary":"Like comment","description":"Like or upvote a comment on a post. Supported platforms: Facebook, X, Bluesky, Reddit, LinkedIn, and Instagram in limited release (see below).\n\n### Platform notes\n\n- Bluesky: the cid (content identifier) is required in the request body.\n- LinkedIn: pass the composite comment URN returned by the comments endpoints as commentId. An optional reactionType picks the reaction (defaults to LIKE).\n- LinkedIn: accounts connected before the social-feed scopes were requested get a 403 with code `linkedin_reconnect_required`.\n\n### Instagram (limited release)\n\nInstagram is in LIMITED RELEASE and not generally available. The call needs `instagram_manage_engagement`, which Meta has so far granted this app only under Standard Access.\n\nIt works for app admins, developers and testers of our Meta app, and returns a 403 with code `PLATFORM_BETA_RESTRICTED` for every other account. That restriction lifts when Meta App Review grants Advanced Access; the constraints below apply once it does.\n\nInstagram covers comments and replies on feed posts, reels and carousels. Only an account connected through Facebook Login can be granted `instagram_manage_engagement`.\n\n- 400 `instagram_likes_require_facebook_login`: the account is an Instagram Login connection.\n- 403 `reconnect_required`: the account's token predates the permission.\n- Content from private accounts cannot be liked.\n\nInstagram enforces a burst limit of 50 like or unlike calls per 5 seconds per Instagram account. Exceeding it locks that account out of the like API for an hour, so pace bulk loops.\n","tags":["Comments"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"}},{"name":"commentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"The account ID"},"reactionType":{"type":"string","enum":["LIKE","PRAISE","EMPATHY","INTEREST","APPRECIATION","ENTERTAINMENT"],"description":"(LinkedIn only) Reaction to create. Defaults to LIKE; ignored on other platforms."},"cid":{"type":"string","description":"(Bluesky only) Content identifier for the comment"}}}}}},"responses":{"200":{"description":"Comment liked","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"commentId":{"type":"string"},"liked":{"type":"boolean"},"likeUri":{"type":"string","description":"(Bluesky only) URI to use for unliking"},"alreadyReacted":{"type":"boolean","description":"LinkedIn only: the account already had this exact reaction, so nothing was created"},"reactionType":{"type":"string","description":"LinkedIn only: the reaction type now in effect"},"platform":{"type":"string"}}}}}},"400":{"description":"Platform does not support liking comments"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required, or the account is missing the platform permission"},"409":{"x-summary":"The LinkedIn account already holds a reaction on this target: remove it before creating another.","description":"LinkedIn only: the account already holds a reaction on this target, either of a different type or one LinkedIn does not let this account read (code invalid_resource_state); remove it before creating another."}}},"delete":{"x-resource-group":"engagement","operationId":"unlikeInboxComment","summary":"Unlike comment","description":"Remove a like from a comment. Supported platforms: Facebook, X, Bluesky,\nReddit, LinkedIn, and Instagram in limited release. For Bluesky, the likeUri query\nparameter is required. Instagram has the same limited release, Facebook Login,\n`instagram_manage_engagement` and burst-limit constraints as liking.\n","tags":["Comments"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"}},{"name":"commentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"likeUri","in":"query","schema":{"type":"string"},"description":"(Bluesky only) The like URI returned when liking"}],"responses":{"200":{"description":"Comment unliked","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"commentId":{"type":"string"},"liked":{"type":"boolean"},"platform":{"type":"string"}}}}}},"400":{"description":"Platform does not support unliking comments"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required, or the account is missing the platform permission"}}}},"/v1/inbox/posts/{postId}/like":{"post":{"x-resource-group":"messages","operationId":"likePost","summary":"Like post","description":"Like (or react to) a post as a connected account.\n\n### Platform support\n\n- Supported: LinkedIn, X, Facebook, YouTube, Bluesky, and Instagram in limited release (see below).\n- Threads, TikTok and Pinterest expose no like endpoint in their APIs and return 400.\n- Reddit returns 400 too, pointing at `POST /v1/accounts/{accountId}/reddit-vote`, which covers upvote, downvote and clear on both posts and comments.\n\n### Liking as another account\n\nThe account does not have to be the one that published the post, which is what makes executive engagement possible: pass an exec's `accountId` and the brand post's ID.\n\n`postId` accepts either a Zernio post ID or the platform's native post ID. A Zernio post ID resolves to the entry for `accountId`, falling back to the post's single entry on the same platform. Two entries on that platform is a 400, so pass the native ID.\n\n### LinkedIn and YouTube\n\nLinkedIn requires the `w_member_social_feed` / `w_organization_social_feed` scopes, which are not retroactive. Accounts connected before those were requested get a 403 with code `linkedin_reconnect_required` until the user reconnects the account.\n\nYouTube spends 50 quota units per call.\n\n### Instagram (limited release)\n\nInstagram is in LIMITED RELEASE and not generally available. The call needs `instagram_manage_engagement`, which Meta has so far granted this app only under Standard Access.\n\nSo it works for app admins, developers and testers of our Meta app, and returns a 403 with code `PLATFORM_BETA_RESTRICTED` for every other account. That restriction lifts when Meta App Review grants Advanced Access; the constraints below apply once it does.\n\n- Instagram covers feed images, reels and carousels (stories and private-account media are not likeable).\n- Only an account connected through Facebook Login can be granted `instagram_manage_engagement`. An Instagram Login connection returns a 400 with code `instagram_likes_require_facebook_login`.\n- An account whose token predates the permission returns a 403 with code `reconnect_required`.\n- Instagram enforces a burst limit of 50 like or unlike calls per 5 seconds per Instagram account. Exceeding it locks that account out of the like API for an hour, so pace bulk loops.\n","tags":["Comments"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"},"description":"Zernio post ID or the platform's native post ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"The account acting as the liker"},"reactionType":{"type":"string","enum":["LIKE","PRAISE","EMPATHY","INTEREST","APPRECIATION","ENTERTAINMENT"],"description":"(LinkedIn only) Reaction to create. Defaults to LIKE; ignored on other platforms."},"cid":{"type":"string","description":"(Bluesky only) Content identifier of the post"}}}}}},"responses":{"200":{"description":"Post liked","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"postId":{"type":"string","description":"The resolved native post ID"},"platform":{"type":"string"},"liked":{"type":"boolean"},"likeUri":{"type":"string","description":"(Bluesky only) URI to use for unliking"},"alreadyReacted":{"type":"boolean","description":"LinkedIn only: the account already had this exact reaction, so nothing was created"},"reactionType":{"type":"string","description":"LinkedIn only: the reaction type now in effect"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required, or the account is missing the platform scope"},"404":{"description":"Account or post not found"},"409":{"x-summary":"The LinkedIn account already holds a reaction on this target: remove it before creating another.","description":"LinkedIn only: the account already holds a reaction on this target, either of a different type or one LinkedIn does not let this account read (code invalid_resource_state); remove it before creating another."}}},"delete":{"x-resource-group":"messages","operationId":"unlikePost","summary":"Unlike post","description":"Remove this account's like from a post.\n\nSupported platforms: LinkedIn, X, Facebook, YouTube, Bluesky, and Instagram in limited release.\n\n- YouTube: this clears the rating.\n- Instagram: has the same limited release, Facebook Login, `instagram_manage_engagement` and burst-limit constraints as liking.\n- Bluesky: `likeUri` (returned when the post was liked) is required.\n- Reddit: uses `POST /v1/accounts/{accountId}/reddit-vote` with `direction: 0`.\n","tags":["Comments"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"},"description":"Zernio post ID or the platform's native post ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"likeUri","in":"query","schema":{"type":"string"},"description":"(Bluesky only) The like URI returned when liking"}],"responses":{"200":{"description":"Post unliked","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"postId":{"type":"string","description":"The resolved native post ID"},"platform":{"type":"string"},"liked":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required, or the account is missing the platform scope"},"404":{"description":"Account or post not found"}}}},"/v1/inbox/comments/{postId}/{commentId}/private-reply":{"post":{"x-resource-group":"messages","operationId":"sendPrivateReplyToComment","summary":"Send private reply","description":"Send a direct message to the author of a comment. Supported on Instagram and Facebook only.\n\nOne reply per comment, must be sent within 7 days.\n\n### Interactive elements\n\nOptionally attach one of these (`quickReplies` and `buttons` are mutually exclusive):\n\n- `quickReplies`: chips above the keyboard, max 13. Chips do not render in the Instagram Message Requests folder.\n- `buttons`: 1-3 inline postback/url buttons rendered in the same bubble via Meta's button_template.\n\n### Non-followers on Instagram\n\nInstagram can refuse buttons, cards and attachments to commenters who do not follow the account. This is Meta code 2, subcode 1545133, returned here as a non-retryable 400 that says so.\n\nThe refusal is uneven: most accounts do not get it, and an affected account gets it on many of its non-followers. Only that account's own past refusals show whether it is affected.\n\nThe failed call still consumes the comment's single private reply. On an affected account, send plain text to reach non-followers and add buttons once they reply.\n\n### Errors\n\n- 400 with `details.privateReplyConsumed: true`: the comment's single private reply is spent (by this call or an earlier one). Never retry it.\n- 502: Meta answered a server error after receiving the reply. It carries `details.privateReplyOutcome: \"unknown\"`. The reply is usually delivered and the comment's private reply spent, so check the conversation before retrying.\n\n### Recording\n\nThe reply is recorded in the inbox conversation with the commenter (`sentVia` `api` for key auth, `human` for a session) and fires `message.sent` once.\n","tags":["Comments"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"},"description":"The media/post ID (Instagram media ID or Facebook post ID)"},{"name":"commentId","in":"path","required":true,"schema":{"type":"string"},"description":"The comment ID to send a private reply to"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","message"],"properties":{"accountId":{"type":"string","description":"The account ID (Instagram or Facebook)"},"message":{"type":"string","description":"The message text to send as a private DM"},"quickReplies":{"type":"array","description":"Optional quick-reply chips appended to the message. Visible only in the\nInstagram and Messenger apps (not on web). Maximum 13 entries. Mutually\nexclusive with `buttons`. Note: chips do NOT render in the Instagram\nMessage Requests folder where DMs from non-followers land. Use `buttons`\ninstead for cold reach.\n","maxItems":13,"items":{"type":"object","required":["title","payload"],"properties":{"title":{"type":"string","maxLength":20,"description":"Label shown on the chip. Truncated by Meta beyond 20 characters."},"payload":{"type":"string","description":"Opaque value returned in the inbound webhook when the user taps the chip."},"imageUrl":{"type":"string","format":"uri","description":"Optional thumbnail shown next to the chip title."}}}},"buttons":{"type":"array","description":"Optional 1-3 inline buttons rendered as part of the same message bubble\nvia Meta's button_template. Visible in the Instagram Message Requests\nfolder (unlike quick replies). Mutually exclusive with `quickReplies`.\n","minItems":1,"maxItems":3,"items":{"oneOf":[{"type":"object","required":["type","title","url"],"properties":{"type":{"type":"string","enum":["url"]},"title":{"type":"string","maxLength":20,"description":"Label shown on the button."},"url":{"type":"string","format":"uri","description":"URL opened when the button is tapped."}}},{"type":"object","required":["type","title","payload"],"properties":{"type":{"type":"string","enum":["postback"]},"title":{"type":"string","maxLength":20,"description":"Label shown on the button."},"payload":{"type":"string","description":"Opaque value returned in the inbound webhook when the user taps the button."}}},{"type":"object","required":["type","title","phone"],"properties":{"type":{"type":"string","enum":["phone"]},"title":{"type":"string","maxLength":20,"description":"Label shown on the button. Facebook only."},"phone":{"type":"string","description":"E.164 phone number dialed when tapped. Facebook only."}}}]}}}},"examples":{"textOnly":{"summary":"Plain text reply","value":{"accountId":"507f1f77bcf86cd799439011","message":"Hi! Thanks for your comment. I wanted to reach out privately to help with your question."}},"withQuickReplies":{"summary":"Comment-to-DM with quick replies","value":{"accountId":"507f1f77bcf86cd799439011","message":"Thanks for commenting! Want me to send the link?","quickReplies":[{"title":"Yes, send it","payload":"SEND_LINK"},{"title":"No thanks","payload":"DECLINE"}]}},"withButtons":{"summary":"Comment-to-DM with inline buttons (recommended for cold reach)","value":{"accountId":"507f1f77bcf86cd799439011","message":"Thanks for commenting! Tap below to grab the link.","buttons":[{"type":"url","title":"Get the link","url":"https://tribenest.co/landing"},{"type":"postback","title":"Remind me later","payload":"REMIND_LATER"}]}}}}}},"responses":{"200":{"description":"Private reply sent successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"messageId":{"type":"string","description":"The ID of the sent message"},"commentId":{"type":"string","description":"The comment ID that was replied to"},"platform":{"type":"string","enum":["instagram","facebook"],"example":"instagram"}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"platformNotSupported":{"summary":"Platform not supported","value":{"error":"Private replies to comments are only supported on Instagram and Facebook.","type":"invalid_request_error","code":"invalid_field_value","param":"accountId"}},"followGated":{"summary":"Media refused, commenter does not follow the account (reply consumed)","value":{"error":"Instagram refused this private reply because it carries a card, buttons or an attachment and the commenter does not follow this account. Meta applies this refusal unevenly: most accounts do not get it, an affected account gets it on many of its non-followers. This attempt consumed the comment's single private reply, so do not retry it; send a text-only private reply to reach other non-followers.","type":"platform_error","code":"platform_api_error","platform":"instagram","platformError":{"code":2,"error_subcode":1545133,"is_transient":false,"message":"Service temporarily unavailable","error_user_title":"Your message can't be delivered","error_user_msg":"You can't send media to Someone unless they follow you."},"details":{"privateReplyConsumed":true}}},"alreadyReplied":{"summary":"Already sent a private reply (reply consumed, Meta subcode 2534023)","value":{"error":"A private reply has already been sent to this comment. Instagram only allows one private reply per comment.","type":"platform_error","code":"platform_api_error","platform":"instagram","details":{"privateReplyConsumed":true}}},"commentTooOld":{"summary":"Comment older than 7 days","value":{"error":"The comment is older than 7 days. Instagram only allows private replies within 7 days of the comment being posted.","type":"platform_error","code":"platform_api_error","platform":"instagram"}},"declinedByMeta":{"summary":"Meta declined the private reply on this media (subcode 2534066, reply NOT consumed)","value":{"error":"Instagram declined this private reply (Meta error 2534066). Despite Meta's wording, the token and permissions are fine and the comment ID is valid, so reconnecting the account or retrying this comment will not change the result.","type":"platform_error","code":"platform_api_error","platform":"instagram","platformError":{"code":200,"error_subcode":2534066,"type":"IGApiException","message":"Please check if access token has enough IG permissions granular scopes for IG private reply. Or, verify if the comment ID is valid"}}},"missingMessage":{"summary":"Missing message","value":{"error":"message is required and must be a non-empty string","type":"invalid_request_error","code":"missing_required_field","param":"message"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The Inbox addon is required, or the team has no payment method and used its free monthly messages: add a payment method.","description":"Inbox addon required, or code `message_allowance_exceeded` when the team has no payment method on file and has used its free monthly messages."},"404":{"description":"Account not found"},"502":{"x-summary":"Meta returned a server error after receiving the reply and the outcome is unknown, usually delivered: do not retry blindly.","description":"Meta returned a server error after receiving the reply; outcome unknown, usually delivered. Do not retry blindly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Meta did not confirm this private reply (server error or no response). In most observed cases the reply was still delivered and the comment's single private reply is spent, so do not retry: check the conversation first. A retry on a spent comment answers 400 with details.privateReplyConsumed: true.","type":"platform_error","code":"platform_api_error","platform":"instagram","platformError":{"message":"An unknown error has occurred.","type":"OAuthException","code":1},"details":{"privateReplyOutcome":"unknown"}}}}}}}},"/v1/twitter/retweet":{"post":{"x-resource-group":"engagement","operationId":"retweetPost","summary":"Retweet a post","description":"Retweet (repost) a tweet by ID.\nRate limit: 50 requests per 15-min window. Shares the 300/3hr creation limit with tweet creation.\n","tags":["Twitter Engagement"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","tweetId"],"properties":{"accountId":{"type":"string","description":"The account ID"},"tweetId":{"type":"string","description":"The ID of the tweet to retweet"}}}}}},"responses":{"200":{"description":"Tweet retweeted","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"tweetId":{"type":"string"},"retweeted":{"type":"boolean"},"platform":{"type":"string","example":"twitter"}}}}}},"400":{"description":"Bad request or platform limitation"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/BalanceRequired"},"403":{"description":"X rejected the request (e.g. suspended account, missing OAuth scope)"},"404":{"description":"Account not found"}}},"delete":{"x-resource-group":"engagement","operationId":"undoRetweet","summary":"Undo retweet","description":"Undo a retweet (un-repost a tweet).\n","tags":["Twitter Engagement"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"tweetId","in":"query","required":true,"schema":{"type":"string"},"description":"The ID of the original tweet to un-retweet"}],"responses":{"200":{"description":"Retweet undone","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"tweetId":{"type":"string"},"retweeted":{"type":"boolean","example":false},"platform":{"type":"string","example":"twitter"}}}}}},"400":{"description":"Bad request"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"X rejected the request (e.g. suspended account, missing OAuth scope)"},"404":{"description":"Account not found"}}}},"/v1/twitter/bookmark":{"post":{"x-resource-group":"engagement","operationId":"bookmarkPost","summary":"Bookmark a tweet","description":"Bookmark a tweet by ID.\nRequires the bookmark.write OAuth scope.\nRate limit: 50 requests per 15-min window.\n","tags":["Twitter Engagement"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","tweetId"],"properties":{"accountId":{"type":"string","description":"The account ID"},"tweetId":{"type":"string","description":"The ID of the tweet to bookmark"}}}}}},"responses":{"200":{"description":"Tweet bookmarked","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"tweetId":{"type":"string"},"bookmarked":{"type":"boolean"},"platform":{"type":"string","example":"twitter"}}}}}},"400":{"description":"Bad request or platform limitation"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/BalanceRequired"},"403":{"description":"X rejected the request (e.g. suspended account, missing OAuth scope)"},"404":{"description":"Account not found"}}},"delete":{"x-resource-group":"engagement","operationId":"removeBookmark","summary":"Remove bookmark","description":"Remove a bookmark from a tweet.\n","tags":["Twitter Engagement"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"tweetId","in":"query","required":true,"schema":{"type":"string"},"description":"The ID of the tweet to unbookmark"}],"responses":{"200":{"description":"Bookmark removed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"tweetId":{"type":"string"},"bookmarked":{"type":"boolean","example":false},"platform":{"type":"string","example":"twitter"}}}}}},"400":{"description":"Bad request"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"X rejected the request (e.g. suspended account, missing OAuth scope)"},"404":{"description":"Account not found"}}}},"/v1/twitter/follow":{"post":{"x-resource-group":"engagement","operationId":"followUser","summary":"Follow a user","description":"Follow a user on X.\nRequires the follows.write OAuth scope.\nFor protected accounts, a follow request is sent instead (pending_follow will be true).\n","tags":["Twitter Engagement"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","targetUserId"],"properties":{"accountId":{"type":"string","description":"The account ID"},"targetUserId":{"type":"string","description":"The X ID of the user to follow"}}}}}},"responses":{"200":{"description":"User followed or follow request sent","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"targetUserId":{"type":"string"},"following":{"type":"boolean"},"pending_follow":{"type":"boolean","description":"True if the target account is protected and a follow request was sent"},"platform":{"type":"string","example":"twitter"}}}}}},"400":{"description":"Bad request or platform limitation"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/BalanceRequired"},"403":{"description":"X rejected the request (e.g. suspended account, missing OAuth scope)"},"404":{"description":"Account not found"}}},"delete":{"x-resource-group":"engagement","operationId":"unfollowUser","summary":"Unfollow a user","description":"Unfollow a user on X.\n","tags":["Twitter Engagement"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"targetUserId","in":"query","required":true,"schema":{"type":"string"},"description":"The X ID of the user to unfollow"}],"responses":{"200":{"description":"User unfollowed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"targetUserId":{"type":"string"},"following":{"type":"boolean","example":false},"platform":{"type":"string","example":"twitter"}}}}}},"400":{"description":"Bad request"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"X rejected the request (e.g. suspended account, missing OAuth scope)"},"404":{"description":"Account not found"}}}},"/v1/twitter/search":{"get":{"x-resource-group":"engagement","operationId":"searchTweets","summary":"Search recent tweets","description":"Search public tweets from the last 7 days matching an X search query, e.g. to discover tweets to reply to.\n\n### Query syntax\n\nThe query string is passed through to X unchanged and supports X's search operators: `from:user`, `-is:retweet`, `is:reply`, `lang:en`, `\"exact phrase\"`, `conversation_id:123`, boolean `OR`, ...\n\nStandalone operators like `is:` / `has:` / `lang:` must be combined with a keyword or `from:` clause.\n\n### Replying\n\nTo reply to a found tweet, pass its `id` as the twitter platform entry's `platformSpecificData.replyToTweetId` when creating a post.\n\n### Rate limit\n\n300 requests per 15-min window per connected account.\n","tags":["Twitter Engagement"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The account ID"},{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":512},"description":"X search query, max 512 characters. Operators are passed through unchanged; X rejects malformed queries with a 400."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":10,"maximum":100,"default":10},"description":"Results per page. X requires a minimum of 10; values below 10 are rejected."},{"name":"sinceId","in":"query","schema":{"type":"string","pattern":"^[0-9]{1,19}$"},"description":"Only return tweets with an ID greater than (more recent than) this numeric tweet ID. Non-numeric values are rejected with 400."},{"name":"untilId","in":"query","schema":{"type":"string","pattern":"^[0-9]{1,19}$"},"description":"Only return tweets with an ID less than (older than) this numeric tweet ID. Non-numeric values are rejected with 400."},{"name":"startTime","in":"query","schema":{"type":"string","format":"date-time"},"description":"Oldest UTC timestamp (ISO 8601, inclusive), within the last 7 days"},{"name":"endTime","in":"query","schema":{"type":"string","format":"date-time"},"description":"Newest UTC timestamp (ISO 8601, exclusive), within the last 7 days"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor from a previous response"},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["recency","relevancy"],"default":"recency"}}],"responses":{"200":{"description":"Matching tweets","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"tweets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"created":{"type":"string","format":"date-time"},"conversationId":{"type":"string"},"inReplyToTweetId":{"type":["string","null"],"description":"Parent tweet ID when the result is itself a reply"},"lang":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string"},"displayName":{"type":"string"},"avatar":{"type":"string"},"verifiedType":{"type":"string"}}},"likeCount":{"type":"integer"},"replyCount":{"type":"integer"},"retweetCount":{"type":"integer"},"quoteCount":{"type":"integer"},"platform":{"type":"string","example":"twitter"}}}},"pagination":{"type":"object","properties":{"hasMore":{"type":"boolean"},"cursor":{"type":["string","null"]}}},"meta":{"type":"object","properties":{"resultCount":{"type":"integer"},"newestId":{"type":["string","null"]},"oldestId":{"type":["string","null"]},"platform":{"type":"string","example":"twitter"}}}}}}}},"400":{"description":"Bad request (invalid params, or X rejected the query as malformed)"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"X API spend cap reached for this billing period"},"403":{"description":"X analytics capability not enabled for this account (code X_ANALYTICS_NOT_ENABLED)"},"404":{"description":"Account not found"},"429":{"description":"X search rate limit exceeded (300 requests per 15 minutes)"}}}},"/v1/twitter/tweet":{"get":{"x-resource-group":"engagement","operationId":"getTweet","summary":"Look up a tweet","description":"Resolve a single tweet by ID or URL into its text, author and public metrics.\n\nUse this to render a post you are referencing, e.g. the tweet quoted by a quote-style post.\nUnlike `/v1/twitter/search` this is not limited to the last 7 days and works for any tweet\nvisible to the connected account.\n\nBilled as an X posts read ($0.005). Repeat lookups of the same tweet within the same UTC day\nare charged once.\n","tags":["Twitter Engagement"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The account ID whose X token is used for the lookup"},{"name":"tweetId","in":"query","required":true,"schema":{"type":"string"},"description":"Numeric tweet ID or a tweet URL (e.g. https://x.com/user/status/123...). The same name the other /v1/twitter operations use (retweet, bookmark)."},{"name":"id","in":"query","required":false,"deprecated":true,"schema":{"type":"string"},"description":"Alias of tweetId, kept for existing callers"}],"responses":{"200":{"description":"The resolved tweet","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"tweet":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"created":{"type":"string","format":"date-time"},"conversationId":{"type":"string"},"inReplyToTweetId":{"type":["string","null"],"description":"Parent tweet ID when the tweet is itself a reply"},"lang":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string"},"displayName":{"type":"string"},"avatar":{"type":"string"},"verifiedType":{"type":"string"}}},"likeCount":{"type":"integer"},"replyCount":{"type":"integer"},"retweetCount":{"type":"integer"},"quoteCount":{"type":"integer"},"platform":{"type":"string","example":"twitter"}}}}}}}},"400":{"x-summary":"The tweetId or accountId is missing or malformed, or the request has an unknown query parameter: fix the request.","description":"Missing or malformed tweetId or accountId, or a query parameter this endpoint does not know (the message lists the accepted ones; nothing is silently ignored)"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"X API spend cap reached for this billing period"},"403":{"description":"X analytics capability not enabled for this account (code X_ANALYTICS_NOT_ENABLED), or the tweet author is protected or suspended"},"404":{"description":"Account not found, or the tweet was deleted or never existed"},"429":{"description":"X rate limit exceeded"}}}},"/v1/inbox/mentions":{"get":{"x-resource-group":"engagement","operationId":"listInboxMentions","summary":"List mentions","description":"Returns mentions of your connected accounts from the last 7 days. Requires Inbox addon.\n\n### LinkedIn\n\nOrganization mentions, delivered by webhooks and a background pull.\n\n### Instagram\n\nComment mentions (someone tags the account in a comment on their own media) and caption mentions (someone tags it in their media caption), delivered by the Meta `mentions` webhook.\n\n- Only accounts connected through Facebook Login receive them.\n- Comments on the account's own posts are never listed, even when they contain its @handle.\n- Their text is read from Instagram in the background after the first request, so `content` can be empty on the first read.\n- Pass `mediaId` and `commentId` to `POST /v1/inbox/mentions/reply` to answer one.\n\n### Facebook\n\nPost mentions (someone tags the Page in a post) and comment mentions (someone tags it in a comment), delivered by the Page `mention` webhook with their text.\n\n- Comments on the Page's own posts and anything the Page wrote itself are never listed.\n- Facebook mentions cannot be replied to through `POST /v1/inbox/mentions/reply`.\n","tags":["Mentions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Filter by account ID"},{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Filter by profile ID"},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort order by publishedAt"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor for pagination (ID of the last item from the previous page)"}],"responses":{"200":{"description":"Paginated list of mentions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Mention document ID"},"platform":{"type":"string","enum":["linkedin","instagram","facebook"]},"type":{"type":["string","null"],"enum":["caption","post","comment",null],"description":"Instagram and Facebook: `caption` when the Instagram account was tagged in a media caption, `post` when the Facebook Page was tagged in a post, `comment` when either was tagged in a comment. Null for LinkedIn."},"mediaId":{"type":["string","null"],"description":"Instagram only: ID of the media the account was mentioned in (or under). Null for LinkedIn and Facebook."},"postId":{"type":["string","null"],"description":"Facebook only: ID of the post the Page was mentioned in (or under). Null for LinkedIn and Instagram."},"commentId":{"type":["string","null"],"description":"Instagram and Facebook: ID of the comment that mentioned the account. Null for caption and post mentions and for LinkedIn."},"accountId":{"type":"string"},"accountUsername":{"type":"string"},"content":{"type":"string","description":"Text that mentioned you: the post text on LinkedIn, the caption or comment text on Instagram, the post or comment text on Facebook. Empty until it has been read."},"permalink":{"type":["string","null"],"description":"URL to the source post on LinkedIn. Null on Instagram and Facebook."},"authorUrn":{"type":["string","null"],"description":"LinkedIn URN of the person who mentioned you, the Instagram-scoped ID of the commenter on an Instagram comment mention, or the ID of the Facebook user or Page that mentioned your Page when Meta sends it."},"authorName":{"type":["string","null"],"description":"Display name of the author, resolved from authorUrn on LinkedIn (null when LinkedIn does not allow resolving the profile) and taken from the webhook on Facebook."},"authorUsername":{"type":["string","null"],"description":"LinkedIn vanity name of the author (the slug in their profile URL), or the Instagram username of the commenter or media owner."},"authorPicture":{"type":["string","null"],"description":"Profile picture URL of the author. LinkedIn CDN URLs expire after some time, so fetch promptly rather than storing long-term."},"organizationalEntity":{"type":"string","description":"URN of the LinkedIn organization that was mentioned, the Instagram user ID of the mentioned account, or the ID of the mentioned Facebook Page."},"publishedAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","properties":{"hasMore":{"type":"boolean"},"cursor":{"type":["string","null"]}}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"sortOrder":{"type":"string","enum":["asc","desc"]}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"}}}},"/v1/inbox/mentions/reply":{"post":{"x-resource-group":"engagement","operationId":"replyToMention","summary":"Reply to a mention","description":"Reply to a mention of the connected account. Supported on Instagram only.\n\nTwo shapes, selected by whether `commentId` is present:\n\n- **Comment mention** (someone @mentioned the account inside a comment): pass both\n  `mediaId` and `commentId`. Instagram posts a reply under that comment.\n- **Caption mention** (someone @mentioned the account in their media caption, so no\n  comment exists): pass `mediaId` only. Instagram posts a comment on their media.\n\nStory mentions are not supported by Instagram's API.\n\n`GET /v1/inbox/mentions` returns Instagram mentions with the `mediaId` and `commentId`\nto pass here.\n","tags":["Mentions"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","mediaId","message"],"properties":{"accountId":{"type":"string","description":"The Instagram account ID"},"mediaId":{"type":"string","description":"The ID of the media the account was mentioned in"},"commentId":{"type":"string","description":"The mentioning comment's ID. Omit for a caption mention."},"message":{"type":"string","description":"The reply text"}}},"example":{"accountId":"60f7a1b2c3d4e5f6a7b8c9d0","mediaId":"17895695668004550","commentId":"17870913561140000","message":"Thanks for the shout-out!"}}}},"responses":{"200":{"description":"Reply posted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string","description":"ID of the created reply or comment"}}},"example":{"success":true,"id":"17912345678901234"}}}},"400":{"description":"Platform does not support replying to mentions (code: platform_not_supported), or missing mediaId/message."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"description":"Account not found"},"502":{"x-summary":"Instagram was unreachable or returned an unclassified error: retry later, and note that Instagram 4xx statuses pass through unchanged.","description":"Instagram was unreachable or returned an unclassified error. Instagram 4xx statuses are forwarded as-is."}}}},"/v1/inbox/reviews":{"get":{"x-resource-group":"engagement","operationId":"listInboxReviews","summary":"List reviews","description":"Fetch reviews from all connected Facebook Pages and Google Business Profile accounts. Aggregates data with filtering and sorting options.\nSupported platforms: Facebook, Google Business Profile.\n\nEach account's reviews are read from the platform page by page within a 20-second budget per request, so very large accounts can come back truncated. Each account's listing is cached for up to 60 seconds.\n","tags":["Reviews"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"profileId","in":"query","schema":{"type":"string"}},{"name":"platform","in":"query","schema":{"type":"string","enum":["facebook","googlebusiness"]}},{"name":"minRating","in":"query","schema":{"type":"integer","minimum":1,"maximum":5}},{"name":"maxRating","in":"query","schema":{"type":"integer","minimum":1,"maximum":5}},{"name":"hasReply","in":"query","schema":{"type":"boolean"},"description":"Filter by reply status"},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["date","rating"],"default":"date"}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Filter by specific account ID"}],"responses":{"200":{"description":"Aggregated reviews","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Review identifier. For Google Business Profile this is the full review resource name (accounts/{accountId}/locations/{locationId}/reviews/{reviewId}), so it also encodes the location."},"platform":{"type":"string"},"accountId":{"type":"string"},"accountUsername":{"type":"string"},"locationId":{"type":"string","description":"Bare Google Business Profile location id the review belongs to. Google Business Profile only; absent for other platforms."},"locationName":{"type":["string","null"],"description":"Human-readable Google Business Profile location display name. Google Business Profile only; absent for other platforms."},"reviewer":{"type":"object","properties":{"id":{"type":["string","null"]},"name":{"type":"string"},"profileImage":{"type":["string","null"]}}},"rating":{"type":"integer"},"recommendationType":{"type":["string","null"],"enum":["positive","negative",null],"description":"Facebook recommendation: positive means recommends, negative means does not recommend. Null or absent when unavailable; absent for other platforms. Independent of the numeric rating."},"text":{"type":"string"},"created":{"type":"string","format":"date-time"},"hasReply":{"type":"boolean"},"hasPhotos":{"type":"boolean","description":"Whether the review has at least one photo. Google Business Profile only; always false for other platforms."},"photoCount":{"type":"integer","description":"Number of photos attached to the review (photos only; videos are not counted). Google Business Profile only; 0 for other platforms."},"photos":{"type":"array","description":"Photos attached to the review. Google Business Profile only; always an empty array for other platforms.","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"}}}},"reply":{"type":["object","null"],"properties":{"id":{"type":"string"},"text":{"type":"string"},"created":{"type":"string","format":"date-time"}}},"reviewUrl":{"type":["string","null"]}}}},"pagination":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}},"meta":{"type":"object","properties":{"accountsQueried":{"type":"integer"},"accountsFailed":{"type":"integer"},"failedAccounts":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string"},"accountUsername":{"type":["string","null"]},"platform":{"type":"string"},"error":{"type":"string"},"code":{"type":["string","null"],"description":"Error code if available"},"retryAfter":{"type":["integer","null"],"description":"Seconds to wait before retry (rate limits)"}}}},"lastUpdated":{"type":"string","format":"date-time"},"accountsSkipped":{"type":"array","description":"Connected accounts that were not queried: their platform does not support this feature, or the account is not enabled for it","items":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string"}}}}}},"summary":{"type":"object","properties":{"totalReviews":{"type":"integer"},"averageRating":{"type":["number","null"]}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"}}}},"/v1/inbox/reviews/{reviewId}/reply":{"post":{"x-resource-group":"engagement","operationId":"replyToInboxReview","summary":"Reply to review","description":"Post a reply to a review. Requires accountId in request body.\n\n### Idempotency\n\nSend an `Idempotency-Key` header to make retries safe (e.g. after a client-side timeout where delivery is unknown).\n\n- Same key + same body: replays the original response (with `Idempotent-Replayed: true`) instead of sending the reply to the platform again.\n- Same key + different body: returns 422.\n- A key still in flight: returns 409.\n\nKeys are retained for 24 hours and are scoped to the credential and to this exact path. Reusing a key against a different reviewId returns 422 rather than replaying the other review's response.\n\n### Failed requests\n\nOnly successful (2xx) responses are stored for replay. If the request throws or returns a non-2xx status the key is released, so the header protects the \"request succeeded but the response was lost\" case.\n\nAfter an ambiguous failure (a 5xx or a network timeout), fetch the review before retrying with the same key. Treat a missing reply as inconclusive rather than as proof nothing was sent.\n","tags":["Reviews"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string"},"description":"Review ID (URL-encoded for Google Business Profile)"},{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","message"],"properties":{"accountId":{"type":"string"},"message":{"type":"string"}}}}}},"responses":{"200":{"description":"Reply posted","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"reply":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"created":{"type":"string","format":"date-time"}}},"platform":{"type":"string"}}}}}},"400":{"x-summary":"Facebook permanently refused the reply for this review, which usually already has a Page reply: do not retry.","description":"Facebook refused the reply for this review (code platform_api_error, platform facebook, Meta error 12 echoed in platformError). Permanent for that review: Graph cannot address its underlying post, and it usually already carries a reply from the Page, which the review listing reports under hasReply. Do not retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"x-summary":"The platform no longer has this review, or this account cannot address it: the failure is permanent, so do not retry.","description":"The platform no longer has this review (deleted or not addressable by this account). Permanent for that review: do not retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"$ref":"#/components/responses/IdempotencyKeyInFlight"},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"},"502":{"x-summary":"The platform failed the call with an upstream error or unreadable response: the failure is transient, so retry with backoff.","description":"The platform failed the call (upstream 5xx or an unreadable response). Transient: safe to retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"x-resource-group":"engagement","operationId":"deleteInboxReviewReply","summary":"Delete review reply","description":"Delete a reply to a review (Google Business Profile only). Requires accountId in request body.","tags":["Reviews"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string"}}}}}},"responses":{"200":{"description":"Reply deleted","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"platform":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"},"404":{"x-summary":"The platform no longer has this review or its reply: the failure is permanent, so do not retry.","description":"The platform no longer has this review or its reply. Permanent: do not retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"x-summary":"The platform failed the call with an upstream error or unreadable response: the failure is transient, so retry with backoff.","description":"The platform failed the call (upstream 5xx or an unreadable response). Transient: safe to retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/whatsapp/templates":{"get":{"x-resource-group":"accounts","operationId":"getWhatsAppTemplates","tags":["WhatsApp"],"summary":"List templates","description":"List message templates for the WhatsApp Business Account (WABA) associated with the given account.\nTemplates are fetched directly from the WhatsApp Cloud API. One entry per **name + language**:\na multi-language template appears once per language, each with its own Meta `id`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"description":"WhatsApp account ID","schema":{"type":"string"}},{"name":"name","in":"query","required":false,"description":"Exact template name; returns every language variant of that family.","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"Exact language code (e.g. en_US).","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["APPROVED","REJECTED","PENDING","PAUSED","DISABLED","IN_APPEAL","PENDING_DELETION"]}}],"responses":{"200":{"description":"Templates retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"templates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"WhatsApp template ID"},"name":{"type":"string"},"status":{"type":"string","enum":["APPROVED","PENDING","REJECTED"]},"category":{"type":"string","enum":["AUTHENTICATION","MARKETING","UTILITY"]},"language":{"type":"string"},"message_send_ttl_seconds":{"type":"integer","description":"Only when a custom TTL is set; absent while the category default applies."},"components":{"type":"array","items":{"type":"object"}}}}}}}}}},"400":{"description":"accountId is required or WABA ID not found"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}},"post":{"x-resource-group":"accounts","operationId":"createWhatsAppTemplate","tags":["WhatsApp"],"summary":"Create template","description":"Create a new message template. Supports two modes:\n\nCustom template: Provide components with your own content. Submitted to Meta for review (can take up to 24h).\n\nLibrary template: Provide library_template_name instead of components to use a pre-built template\nfrom Meta's template library. Library templates are pre-approved (no review wait). You can optionally\ncustomize parameters and buttons via library_template_body_inputs and library_template_button_inputs.\n\nBrowse available library templates at: https://business.facebook.com/wa/manage/message-templates/\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","name","category","language"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"},"name":{"type":"string","pattern":"^[a-z][a-z0-9_]*$","description":"Template name (lowercase, letters/numbers/underscores, must start with a letter)"},"category":{"type":"string","enum":["AUTHENTICATION","MARKETING","UTILITY"],"description":"Template category"},"language":{"type":"string","description":"Template language code (e.g., en_US)"},"parameter_format":{"type":"string","enum":["POSITIONAL","NAMED","positional","named"],"description":"Variable style: POSITIONAL ({{1}}, the default) or NAMED ({{customer_name}}). Named templates provide examples via body_text_named_params / header_text_named_params. Inferred as NAMED when omitted but a named-params example is present."},"components":{"type":"array","description":"Template components (header, body, footer, buttons, carousel, limited_time_offer). Required for custom templates, omit when using library_template_name.","minItems":1,"items":{"$ref":"#/components/schemas/WhatsAppTemplateComponent"}},"library_template_name":{"type":"string","description":"Name of a pre-built template from Meta's template library (e.g., \"appointment_reminder\",\n\"auto_pay_reminder_1\", \"address_update\"). When provided, the template is pre-approved\nby Meta with no review wait. Omit components when using this field.\n"},"library_template_body_inputs":{"type":"object","description":"Optional body customizations for library templates. Available options depend on the\ntemplate (e.g., add_contact_number, add_learn_more_link, add_security_recommendation,\nadd_track_package_link, code_expiration_minutes).\n"},"library_template_button_inputs":{"type":"array","description":"Optional button customizations for library templates. Each item specifies button type\nand configuration (e.g., URL, phone number, quick reply).\n","items":{"type":"object","properties":{"type":{"type":"string","enum":["quick_reply","url","phone_number"]},"url":{"type":"object","properties":{"base_url":{"type":"string"}}},"phone_number":{"type":"string"}}}},"message_send_ttl_seconds":{"type":"integer","description":"Delivery validity window in seconds: a message not delivered within it is dropped. Range by category:\n\n- AUTHENTICATION: 30 to 900.\n- UTILITY: 30 to 43200 (12h).\n- MARKETING: 43200 to 2592000 (30 days).\n\n-1 (create only) keeps the 30-day default on AUTHENTICATION and UTILITY. Meta defaults to 600 for AUTHENTICATION and 30 days otherwise. If Meta later recategorises the template, it clears the TTL (read it back to check).\n"}}},"examples":{"custom":{"summary":"Custom template (requires review)","value":{"accountId":"507f1f77bcf86cd799439011","name":"order_confirmation","category":"UTILITY","language":"en_US","components":[{"type":"header","format":"image","example":{"header_handle":["https://example.com/header.jpg"]}},{"type":"body","text":"Your order {{1}} has been confirmed. Expected delivery: {{2}}","example":{"body_text":[["ORD-12345","March 31"]]}},{"type":"footer","text":"Thank you for your purchase"},{"type":"buttons","buttons":[{"type":"quick_reply","text":"Track Order"}]}]}},"library":{"summary":"Library template (pre-approved, no review)","value":{"accountId":"507f1f77bcf86cd799439011","name":"my_appointment_reminder","category":"UTILITY","language":"en_US","library_template_name":"appointment_reminder","library_template_button_inputs":[{"type":"url","url":{"base_url":"https://myapp.com/appointments/{{1}}"}}]}}}}}},"responses":{"200":{"description":"Template created (pre-approved for library templates, pending review for custom)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"template":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","description":"APPROVED for library templates, PENDING for custom"},"category":{"type":"string"},"language":{"type":"string"},"message_send_ttl_seconds":{"type":"integer","description":"Echoed when supplied on the request."}}}}}}}},"400":{"description":"Validation error (invalid name format, missing fields, invalid category)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The shared WhatsApp sandbox account: its templates are read-only."},"404":{"description":"WhatsApp account not found"},"502":{"x-summary":"Meta rejected the request or was unreachable: retry later, and note that Meta 4xx statuses pass through unchanged.","description":"Meta rejected the request or was unreachable. Meta 4xx statuses are forwarded as-is."}}}},"/v1/whatsapp/templates/{templateName}":{"get":{"x-resource-group":"accounts","operationId":"getWhatsAppTemplate","tags":["WhatsApp"],"summary":"Get template","description":"Retrieve one message template variant by name.\n\nMeta stores one template per **name + language**, so a name identifies a family of variants, each with its own Meta id. Pass `language` to address one variant.\n\n### How the variant is resolved\n\n- Without `language`, a name with a single variant resolves to that variant.\n- Without `language`, a name with several returns `409 ambiguous_template` with `details.languages`.\n- A bare language (`es`) matches a single regional variant (`es_ES`). If the family has several regional variants for it, that is also a 409.\n- A full code (`es_ES`) must match exactly.\n\nVariants in `PENDING_DELETION` are not part of the family.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"templateName","in":"path","required":true,"description":"Template name (the family).","schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"description":"WhatsApp account ID","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"Language code of the variant (e.g. en_US, es, pt_BR). Required when the family has several languages.","schema":{"type":"string"}}],"responses":{"200":{"description":"Template retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"template":{"type":"object","properties":{"id":{"type":"string","description":"Meta template id. Unique per language variant; usable on /v1/whatsapp/templates/id/{templateId}."},"name":{"type":"string"},"status":{"type":"string"},"category":{"type":"string"},"language":{"type":"string","description":"The variant actually returned."},"components":{"type":"array","items":{"type":"object"}},"message_send_ttl_seconds":{"type":"integer","description":"Only when a custom TTL is set; absent while the category default applies."},"rejected_reason":{"type":"string","description":"Only when status is REJECTED."},"quality_score":{"type":"object","description":"Post-approval quality (GREEN/YELLOW/RED), when Meta reports one."}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"x-summary":"The account is not found, or no template has that name and language: check both values and read the listed languages.","description":"Account not found, or no template with that name (and language, when given). details.languages lists the family's languages when the name exists (code template_not_found)."},"409":{"x-summary":"The template name exists in several languages and no language was given: send a language, listed in the error details.","description":"The template name exists in several languages and no language was given (code ambiguous_template). details.languages lists them.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"type":{"type":"string","enum":["invalid_request_error"]},"code":{"type":"string","enum":["ambiguous_template"]},"param":{"type":"string","enum":["language"]},"details":{"type":"object","properties":{"languages":{"type":"array","items":{"type":"string"}}}}}}}}},"502":{"x-summary":"Meta rejected the request or was unreachable: retry later, and note that Meta 4xx statuses pass through unchanged.","description":"Meta rejected the request or was unreachable. Meta 4xx statuses are forwarded as-is."}}},"patch":{"x-resource-group":"accounts","operationId":"updateWhatsAppTemplate","tags":["WhatsApp"],"summary":"Update template","description":"Update one variant's components and/or its message_send_ttl_seconds. Name, language and category cannot change after creation.\n\n### Choosing the variant\n\nMeta stores one template per **name + language**, so a name identifies a family of variants, each with its own Meta id. Pass `language` to address one variant.\n\n- Without `language`, a name with a single variant resolves to that variant. A name with several returns `409 ambiguous_template` with `details.languages`.\n- A bare language (`es`) matches a single regional variant (`es_ES`). If the family has several regional variants for it, that is also a 409.\n- A full code (`es_ES`) must match exactly.\n- Variants in `PENDING_DELETION` are not part of the family.\n\n### Editing rules\n\nMeta only allows editing templates in `APPROVED`, `REJECTED` or `PAUSED` state. An approved template can be edited once per 24 hours and up to 10 times per 30 days.\n\n- A component update sends the variant back to Meta for review, so the `status` returned here is normally `PENDING`.\n- A TTL-only update keeps an APPROVED variant approved.\n- A variant already in `PENDING` cannot be edited again until Meta finishes reviewing it.\n\nThe final outcome arrives on the `whatsapp.template.status_updated` webhook (which carries the variant's `templateId` and `language`).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"templateName","in":"path","required":true,"description":"Template name (the family).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"},"language":{"type":"string","description":"Language code of the variant to edit (e.g. en_US, es, pt_BR). Required when the family has several languages. Body only: a language query parameter on PATCH is a 400."},"components":{"type":"array","description":"Updated template components. Optional when only message_send_ttl_seconds changes; at least one of the two is required.","minItems":1,"items":{"$ref":"#/components/schemas/WhatsAppTemplateComponent"}},"message_send_ttl_seconds":{"type":"integer","description":"Delivery validity window in seconds: a message not delivered within it is dropped. Range by category:\n\n- AUTHENTICATION: 30 to 900.\n- UTILITY: 30 to 43200 (12h).\n- MARKETING: 43200 to 2592000 (30 days).\n\n-1 is not accepted here (Meta treats it as an empty edit); send a value in range. Meta defaults to 600 for AUTHENTICATION and 30 days otherwise.\n\nA TTL-only edit keeps an APPROVED template approved, no re-review. If Meta later recategorises the template, it clears the TTL (read it back to check).\n"}}},"example":{"accountId":"507f1f77bcf86cd799439011","language":"es","components":[{"type":"body","text":"Actualizado: tu pedido {{1}} está confirmado. Entrega el {{2}}","example":{"body_text":[["ORD-12345","1 de abril"]]}},{"type":"buttons","buttons":[{"type":"quick_reply","text":"Seguir pedido"}]}]}}}},"responses":{"200":{"description":"Template updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"template":{"type":"object","properties":{"id":{"type":"string","description":"Meta id of the edited variant."},"name":{"type":"string"},"language":{"type":"string","description":"The variant that was edited."},"status":{"type":"string","description":"Approval state read back from Meta after the update, normally PENDING. If the state cannot be read back, the last known status is returned instead.","example":"PENDING"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The shared WhatsApp sandbox account: its templates are read-only."},"404":{"description":"Account not found, or no template with that name (and language, when given) (code template_not_found)."},"409":{"x-summary":"The template name exists in several languages and no language was given: send a language, listed in the error details.","description":"The template name exists in several languages and no language was given (code ambiguous_template). details.languages lists them.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"type":{"type":"string","enum":["invalid_request_error"]},"code":{"type":"string","enum":["ambiguous_template"]},"param":{"type":"string","enum":["language"]},"details":{"type":"object","properties":{"languages":{"type":"array","items":{"type":"string"}}}}}}}}},"502":{"x-summary":"Meta rejected the update or was unreachable: retry later, and note that Meta 4xx statuses pass through unchanged.","description":"Meta rejected the update or was unreachable. Meta 4xx statuses are forwarded as-is."}}},"delete":{"x-resource-group":"accounts","operationId":"deleteWhatsAppTemplate","tags":["WhatsApp"],"summary":"Delete template","description":"Permanently delete a message template.\n\n**Without `language` this deletes every language variant of the name** (Meta's own\ncontract for deletion by name). Pass `language` to delete one variant only; the response\n`scope` says which happened. Meta keeps a deleted approved template in `PENDING_DELETION`\nfor a while and the name cannot be reused for 30 days.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"templateName","in":"path","required":true,"description":"Template name (the family).","schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"description":"WhatsApp account ID","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"Delete only this language variant (e.g. es). Omit to delete the whole family.","schema":{"type":"string"}}],"responses":{"200":{"description":"Template deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"scope":{"type":"string","enum":["all_languages","language"],"description":"Whether the whole family or one variant was deleted."},"language":{"type":"string","description":"The deleted variant; only when scope is language."},"message":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The shared WhatsApp sandbox account: its templates are read-only."},"404":{"description":"Account not found, or (with language) no such variant (code template_not_found)."},"409":{"x-summary":"The language code matched several regional variants, so nothing was deleted: send the full language code of the variant you want removed.","description":"Only with language: a bare code (es) matched several regional variants (es_ES, es_MX), so nothing was deleted (code ambiguous_template). Without language there is no 409: the whole family is deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"type":{"type":"string","enum":["invalid_request_error"]},"code":{"type":"string","enum":["ambiguous_template"]},"param":{"type":"string","enum":["language"]},"details":{"type":"object","properties":{"languages":{"type":"array","items":{"type":"string"}}}}}}}}},"502":{"x-summary":"Meta rejected the request or was unreachable: retry later, and note that Meta 4xx statuses pass through unchanged.","description":"Meta rejected the request or was unreachable. Meta 4xx statuses are forwarded as-is."}}}},"/v1/whatsapp/templates/id/{templateId}":{"get":{"x-resource-group":"accounts","operationId":"getWhatsAppTemplateById","tags":["WhatsApp"],"summary":"Get template by id","description":"Retrieve one template variant by its Meta id, the id every variant of a family has on its own\nand the one the `whatsapp.template.status_updated` webhook carries.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"templateId","in":"path","required":true,"description":"Meta template id (numeric).","schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"description":"WhatsApp account ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Template retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"template":{"type":"object","properties":{"id":{"type":"string","description":"Meta template id. Unique per language variant; usable on /v1/whatsapp/templates/id/{templateId}."},"name":{"type":"string"},"status":{"type":"string"},"category":{"type":"string"},"language":{"type":"string","description":"The variant actually returned."},"components":{"type":"array","items":{"type":"object"}},"message_send_ttl_seconds":{"type":"integer","description":"Only when a custom TTL is set; absent while the category default applies."},"rejected_reason":{"type":"string","description":"Only when status is REJECTED."},"quality_score":{"type":"object","description":"Post-approval quality (GREEN/YELLOW/RED), when Meta reports one."}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found."},"502":{"x-summary":"Meta rejected the request or was unreachable, including for an id the account cannot access: retry later or check the id.","description":"Meta rejected the request (including an id the account cannot access) or was unreachable. Meta 4xx statuses are forwarded as-is."}}},"patch":{"x-resource-group":"accounts","operationId":"updateWhatsAppTemplateById","tags":["WhatsApp"],"summary":"Update template by id","description":"Update one variant's components and/or its message_send_ttl_seconds by its Meta id. Name, language and category cannot change.\n\n### Editing limits\n\n- Meta only allows editing templates in `APPROVED`, `REJECTED` or `PAUSED` state.\n- An approved template can be edited once per 24 hours and up to 10 times per 30 days.\n- A variant already in `PENDING` cannot be edited again until Meta finishes reviewing it.\n\n### Review\n\nA component update sends the variant back to Meta for review, so the `status` returned here is normally `PENDING`. A TTL-only update keeps an APPROVED variant approved.\n\nThe final outcome arrives on the `whatsapp.template.status_updated` webhook (which carries the variant's `templateId` and `language`).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"templateId","in":"path","required":true,"description":"Meta template id (numeric).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"},"components":{"type":"array","description":"Updated template components. Optional when only message_send_ttl_seconds changes; at least one of the two is required.","minItems":1,"items":{"$ref":"#/components/schemas/WhatsAppTemplateComponent"}},"message_send_ttl_seconds":{"type":"integer","description":"Delivery validity window in seconds: a message not delivered within it is dropped.\n\n**Range by category:**\n\n- AUTHENTICATION: 30 to 900.\n- UTILITY: 30 to 43200 (12h).\n- MARKETING: 43200 to 2592000 (30 days).\n\nThe value -1 is not accepted here (Meta treats it as an empty edit); send a value in range. Meta defaults to 600 for AUTHENTICATION and 30 days otherwise.\n\nA TTL-only edit keeps an APPROVED template approved, with no re-review. If Meta later recategorises the template, it clears the TTL (read it back to check).\n"}}}}}},"responses":{"200":{"description":"Template updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"template":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"status":{"type":"string","description":"Approval state read back from Meta after the update, normally PENDING. If the state cannot be read back, the last known status is returned instead.","example":"PENDING"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The shared WhatsApp sandbox account: its templates are read-only."},"404":{"description":"Account not found."},"502":{"x-summary":"Meta rejected the update or was unreachable, including for an id the account cannot access: retry later or check the id.","description":"Meta rejected the update (including an id the account cannot access) or was unreachable. Meta 4xx statuses are forwarded as-is."}}},"delete":{"x-resource-group":"accounts","operationId":"deleteWhatsAppTemplateById","tags":["WhatsApp"],"summary":"Delete template by id","description":"Delete one language variant by its Meta id. Other languages of the same name are untouched.\nThe name cannot be reused for 30 days once its last variant is deleted.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"templateId","in":"path","required":true,"description":"Meta template id (numeric).","schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"description":"WhatsApp account ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Variant deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"scope":{"type":"string","enum":["language"]},"language":{"type":"string"},"message":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The shared WhatsApp sandbox account: its templates are read-only."},"404":{"description":"Account not found."},"502":{"x-summary":"Meta rejected the request or was unreachable, including for an id the account cannot access: retry later or check the id.","description":"Meta rejected the request (including an id the account cannot access) or was unreachable. Meta 4xx statuses are forwarded as-is."}}}},"/v1/whatsapp/calling":{"get":{"x-resource-group":"accounts","operationId":"getWhatsAppCallingConfig","tags":["WhatsApp Calling"],"summary":"Get calling config for an account","description":"Returns the local calling configuration snapshot for the connected WhatsApp account:\n\n- whether calling is enabled;\n- the forward-to destination URI;\n- recording opt-in state;\n- the phone number record id (use as `{id}` on the read-write calling sub-resource at /v1/phone-numbers/{id}/whatsapp/calling);\n- whether SIP digest credentials are stored (the encrypted password itself is never returned).\n\nIt also carries account-level extras (billing eligibility, current-period spend) that the number-keyed GET does not.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"}],"responses":{"200":{"description":"Calling config","content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumberDocId":{"type":"string","description":"Phone number record ID (use on /v1/phone-numbers/{id}/whatsapp/calling)"},"phoneNumber":{"type":"string"},"callingEnabled":{"type":"boolean"},"callDeepLink":{"type":["string","null"],"description":"Public calling deep link (https://wa.me/call/<number>). Tapping it on a phone starts a WhatsApp voice call to this number. Embed it on websites, emails, or QR codes. Null while calling is disabled; not supported by WhatsApp desktop clients."},"forwardTo":{"type":["string","null"],"description":"tel:+E164 / sip:... / wss://... destination"},"recordingEnabled":{"type":"boolean"},"sipAuthUsername":{"type":["string","null"]},"sipAuthPasswordConfigured":{"type":"boolean","description":"True when a SIP digest password is stored. The plaintext is never returned."},"callIconCountries":{"type":["array","null"],"items":{"type":"string","minLength":2,"maxLength":2}},"callerIdMode":{"type":"string","enum":["business","platform"],"description":"Caller ID the forward-leg callee sees on tel: forwards. business = this WhatsApp number; platform = a Zernio number (customer-brought number without verified caller ID; verify via /v1/phone-numbers/{id}/whatsapp/caller-id-verification)."},"callerIdVerified":{"type":"boolean","description":"True once the number completed caller-ID verification."},"maxCallDurationSeconds":{"type":["integer","null"],"description":"Hard cap (seconds) on forwarded calls; null = no cap."},"forwardCallerId":{"type":"string","enum":["business","caller"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp phone number not found for this account"}}}},"/v1/whatsapp/phone-numbers/{id}/calling":{"post":{"x-resource-group":"telephony","operationId":"enableWhatsAppCallingLegacy","deprecated":true,"tags":["WhatsApp Calling"],"summary":"Enable calling on a number","description":"Deprecated alias of `/v1/phone-numbers/{id}/whatsapp/calling`; same contract. New\nintegrations should use that path.\n\nEnable WhatsApp Business Calling on a connected number. Configures\nMeta calling.status=ENABLED with our Telnyx SIP endpoint, fetches and\nstores the Meta-issued SIP password (encrypted), and snapshots the\ncustomer's forward-to destination.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp phone number id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","forwardTo"],"properties":{"accountId":{"type":"string"},"forwardTo":{"type":"string","description":"tel:+E164 / sip:... / wss://... destination"},"sipAuthUsername":{"type":"string"},"sipAuthPassword":{"type":"string","description":"Stored encrypted, never returned by any endpoint."},"recordingEnabled":{"type":"boolean","default":false},"callIconCountries":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2}},"maxCallDurationSeconds":{"type":"integer","minimum":30,"maximum":14400,"description":"Hard cap (seconds) on a forwarded call; the carrier hangs up both legs when it fires. Safety valve against dead-air billing when a destination hangs up but the signal is lost."},"forwardCallerId":{"type":"string","enum":["business","caller"],"default":"business","description":"Caller ID presented to the forward destination. caller = the WhatsApp user's number (sip: destinations only; ignored on tel: forwards). Fixes AI-agent trunks that reject seeing the business number call itself."}}}}}},"responses":{"200":{"description":"Calling enabled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"callingEnabled":{"type":"boolean"},"sipHostname":{"type":"string"},"forwardTo":{"type":"string"},"callerIdMode":{"type":"string","enum":["business","platform"],"description":"Caller ID the forward-leg callee sees on tel: forwards. business = this WhatsApp number; platform = a Zernio number (customer-brought number without verified caller ID)."}}}}}},"400":{"x-summary":"The request is invalid, or Meta refused to enable calling, for example for a number below the required messaging tier: fix it.","description":"Invalid request (including forwardTo set to the number itself), or Meta refused enablement (platform_api_error with platformError.code 138015, for example a production number below the 2,000-recipient messaging tier; Meta public test numbers and Sandbox accounts are exempt)"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp phone number not found"},"422":{"description":"Not eligible to enable calling: not on usage-based billing."}}},"patch":{"x-resource-group":"telephony","operationId":"updateWhatsAppCallingLegacy","deprecated":true,"tags":["WhatsApp Calling"],"summary":"Update calling config","description":"Deprecated alias of `/v1/phone-numbers/{id}/whatsapp/calling`; same contract. New\nintegrations should use that path.\n\nUpdate fields on an already-enabled number. Only fields present in\nthe body are written; `undefined` leaves the stored value alone,\nexplicit `null` clears a nullable field. No Meta side effect, this\nonly changes local routing state consumed by the Telnyx webhook\nhandler.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string"},"forwardTo":{"type":"string"},"sipAuthUsername":{"type":["string","null"]},"sipAuthPassword":{"type":["string","null"]},"recordingEnabled":{"type":"boolean"},"callIconCountries":{"type":["array","null"],"items":{"type":"string","minLength":2,"maxLength":2}},"maxCallDurationSeconds":{"type":["integer","null"],"minimum":30,"maximum":14400,"description":"Hard cap (seconds) on forwarded calls; null clears the cap."},"forwardCallerId":{"type":"string","enum":["business","caller"],"description":"caller = present the WhatsApp user's number to the forward destination (sip: only)."}}}}}},"responses":{"200":{"description":"Updated"},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp phone number not found"},"422":{"description":"Calling must be enabled before settings can be updated"}}},"delete":{"x-resource-group":"telephony","operationId":"disableWhatsAppCallingLegacy","deprecated":true,"tags":["WhatsApp Calling"],"summary":"Disable calling on a number","description":"Deprecated alias of `/v1/phone-numbers/{id}/whatsapp/calling`; same contract. New\nintegrations should use that path.\n\nDisable calling. Sends calling.status=DISABLED to Meta (best-effort)\nand flips the local `callingEnabled` flag off. forwardTo and SIP\ncreds are preserved so a re-enable does not lose the destination.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Disabled"},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp phone number not found"}}}},"/v1/whatsapp/call-permissions":{"get":{"x-resource-group":"contacts","operationId":"getWhatsAppCallPermissions","tags":["WhatsApp Calling"],"summary":"Check call permission","description":"Returns the permission state and the list of available actions for\na given consumer wa_id (e.g. `start_call`, `send_call_permission_request`).\nUse this before placing a call to decide whether to prompt for\nconsent first.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"to","in":"query","required":true,"schema":{"type":"string"},"description":"Consumer wa_id (E.164, leading + optional)"}],"responses":{"200":{"description":"Permission state","content":{"application/json":{"schema":{"type":"object","properties":{"permission":{"type":"object","properties":{"status":{"type":"string","enum":["temporary","no_permission","permanent"]},"expiration_time":{"type":"integer","description":"Unix seconds when temporary"}}},"actions":{"type":"array","items":{"type":"object","properties":{"action_name":{"type":"string","enum":["send_call_permission_request","start_call"]},"can_perform_action":{"type":"boolean"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}}},"/v1/whatsapp/calls":{"post":{"x-resource-group":"messages","operationId":"initiateWhatsAppCall","tags":["WhatsApp Calling"],"summary":"Initiate outbound call","description":"Initiates an outbound Business-Initiated Call. The Telnyx-side SIP\nleg is originated server-side (Option B: SIP-first). Telnyx INVITEs\nMeta directly over TLS:5061 with the SIP digest credentials we\ncaptured at calling-enablement time). No client-side SDP is\nrequired; pass only `accountId` and `to`.\n\nTo send the consumer the call-consent prompt instead of placing a\ncall, pass `action: \"send_call_permission_request\"` (+ optional\n`bodyText`). The consumer must tap Allow in WhatsApp before\n`start_call` is permitted; Meta limits the prompt to 1 per consumer\nper 24h (2 per 7 days) and requires an open 24h service window.\n\n**Idempotency:** send an `Idempotency-Key` header to make retries\nsafe; same key + same body replays the original response instead of\ndialing (and billing) a second call.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","to"],"properties":{"accountId":{"type":"string"},"to":{"type":"string","description":"Consumer wa_id (E.164, leading + optional)"},"action":{"type":"string","enum":["send_call_permission_request"],"description":"Omit to place a call. Set to send the consent prompt instead."},"bodyText":{"type":"string","maxLength":1024,"description":"Body text shown with the consent prompt (send_call_permission_request only)."},"forwardTo":{"type":"string","description":"Per-call destination override. Same accepted shape as the\nnumber's stored forwardTo (tel:+E164, sip:..., wss://...).\n"},"recordOverride":{"type":"boolean"},"biz_opaque_callback_data":{"type":"string","maxLength":512,"description":"Accepted for forward compatibility. Not currently echoed\nback in webhook payloads (SIP-first flow does not pass\nthrough Meta's Graph API where Meta would echo this).\n"}}}}}},"responses":{"200":{"description":"Call originated; lifecycle continues asynchronously via webhooks.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"callId":{"type":"string","description":"Internal Call doc ID"},"telnyxCallControlId":{"type":"string","description":"Telnyx call_control_id of the outbound leg"},"status":{"type":"string","enum":["dialing"]},"direction":{"type":"string","enum":["outbound"]},"to":{"type":"string"},"forwardTo":{"type":["string","null"]},"recordingEnabled":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/BalanceRequired"},"409":{"x-summary":"The recipient has not granted call permission: send a permission request first, then retry.","description":"No active call permission. Send a permission request first."},"422":{"description":"Calling not enabled, BIC country blocked, or missing Meta SIP credentials"},"502":{"description":"Telnyx-side originate failed; the Call doc has been marked failed."}}},"get":{"x-resource-group":"messages","operationId":"listWhatsAppCalls","tags":["WhatsApp Calling"],"summary":"List call history for an account","description":"Compact history listing for a single connected account. Results are\nscoped to the resolved SocialAccount; profile-scoped team members\ncannot read calls on sibling accounts.\n\nCursor pagination: pass the returned `nextCursor` as `before` to fetch\nthe next page (same scheme as `GET /v1/calls`). `since`/`until` remain\nas absolute range filters and combine with the cursor.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["ringing","answered","ended","failed"]}},{"name":"direction","in":"query","schema":{"type":"string","enum":["inbound","outbound"]}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"before","in":"query","schema":{"type":"string","format":"date-time"},"description":"Return calls with startedAt strictly before this instant (use the previous page's nextCursor)."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Calls","content":{"application/json":{"schema":{"type":"object","properties":{"calls":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"direction":{"type":"string","enum":["inbound","outbound"]},"from":{"type":"string"},"to":{"type":"string"},"status":{"type":"string","enum":["ringing","answered","ended","failed"]},"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"},"billing":{"type":"object","properties":{"metaCostUSD":{"type":"number","description":"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 = Telnyx leg + recording (excludes Meta)."},"totalCostUSD":{"type":"number","description":"Full cost incl. the Meta portion you pay directly. Display only."},"currency":{"type":"string"}}}}}},"nextCursor":{"type":["string","null"],"format":"date-time","description":"Pass as `before` for the next page; null on the last page."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/whatsapp/calls/{id}":{"get":{"x-resource-group":"messages","operationId":"getWhatsAppCall","tags":["WhatsApp Calling"],"summary":"Get a single call","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Call","content":{"application/json":{"schema":{"type":"object","properties":{"call":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Call not found"}}}},"/v1/whatsapp/calls/{id}/recording":{"get":{"x-resource-group":"messages","operationId":"getWhatsAppCallRecording","tags":["WhatsApp Calling"],"summary":"Get a call recording","description":"Resolves a fresh, playable MP3 URL for the call's recording.\n\nProvider-signed recording URLs expire ~10 minutes after signing, so the `recordingUrl` stored on the call is usually stale by the time it is played. This endpoint re-signs on demand.\n\n- Default: responds `302 Found` redirecting to the fresh URL (point an `<audio>` element or a link straight at this endpoint).\n- Pass `as=json` to receive `{ url }` instead.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"as","in":"query","schema":{"type":"string","enum":["json"]},"description":"`json` returns `{ url }` instead of a 302 redirect."}],"responses":{"200":{"description":"Recording URL (`as=json` only).","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}}}}}},"302":{"description":"Redirect to a freshly-signed recording URL."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Call not found, or no recording is available for this call"},"502":{"description":"Recording provider lookup failed"}}}},"/v1/whatsapp/calls/estimate":{"get":{"x-resource-group":"messages","operationId":"getWhatsAppCallEstimate","tags":["WhatsApp Calling"],"summary":"Estimate per-minute cost","description":"Returns a zero-markup estimated cost for an outbound call to the\ngiven destination, broken down by Meta + Telnyx + recording line\nitems. Costs are pass-through, no margin applied.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"to","in":"query","required":true,"schema":{"type":"string"}},{"name":"minutes","in":"query","schema":{"type":"integer","minimum":1,"maximum":120}},{"name":"recording","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Estimate","content":{"application/json":{"schema":{"type":"object","properties":{"destinationCountry":{"type":["string","null"]},"perMinuteUsd":{"type":"number"},"breakdown":{"type":"object","properties":{"metaMinutes":{"type":"integer"},"metaCostUSD":{"type":"number","description":"Estimated 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":"Estimated amount Zernio bills you = Telnyx leg + recording (excludes Meta)."},"totalCostUSD":{"type":"number","description":"Estimated full cost incl. the Meta portion you pay directly. Display only."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/calls":{"get":{"x-resource-group":"messages","operationId":"listCalls","tags":["Calls"],"summary":"List all calls (unified history)","description":"Unified call history across ALL of your numbers: both channels\n(WhatsApp Business Calling + regular phone/PSTN), inbound and outbound,\nnewest first. Unlike `GET /v1/voice/calls` (PSTN-only) and\n`GET /v1/whatsapp/calls` (one account at a time), this endpoint needs no\n`accountId` and never requires fanning out one request per number.\n\nAny row can be opened channel-agnostically via `GET /v1/calls/{id}` and\n`GET /v1/calls/{id}/recording`; no branching on `channel` needed. When\nthe counterparty number matches a CRM contact, `contactId` and\n`contactName` are set.\n\nCursor pagination: pass the returned `nextCursor` as `before` to fetch\nthe next page. `nextCursor` is null on the last page.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"channel","in":"query","schema":{"type":"string","enum":["whatsapp","pstn"]}},{"name":"status","in":"query","schema":{"type":"string","enum":["ringing","answered","ended","failed"]}},{"name":"direction","in":"query","schema":{"type":"string","enum":["inbound","outbound"]}},{"name":"number","in":"query","schema":{"type":"string"},"description":"Exact filter: calls involving this number (typically one of YOUR numbers, to scope history to a single line). E.164, leading + optional."},{"name":"search","in":"query","schema":{"type":"string"},"description":"Free-text match on the from/to numbers. Non-digits are stripped, so partial queries like `302` or `+1 302` work."},{"name":"before","in":"query","schema":{"type":"string","format":"date-time"},"description":"Return calls with startedAt strictly before this instant (use the previous page's nextCursor)."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Calls, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"calls":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/CallRecord"},{"type":"object","properties":{"contactName":{"type":"string","description":"CRM contact name for the counterparty, when resolved."}}}]}},"nextCursor":{"type":["string","null"],"format":"date-time","description":"Pass as `before` for the next page; null on the last page."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/calls/{id}":{"get":{"x-resource-group":"messages","operationId":"getCall","tags":["Calls"],"summary":"Get a call (any channel)","description":"Channel-agnostic call detail: works for both WhatsApp and regular\nphone (PSTN) calls, so any row from `GET /v1/calls` can be opened\nwithout branching on `channel`. Returns the full call including\ntranscript segments, with `contactId`/`contactName` set when the\ncounterparty matches a CRM contact.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Call","content":{"application/json":{"schema":{"type":"object","properties":{"call":{"allOf":[{"$ref":"#/components/schemas/CallRecord"},{"type":"object","properties":{"contactName":{"type":"string","description":"CRM contact name for the counterparty, when resolved."}}}]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Call not found"}}}},"/v1/calls/{id}/recording":{"get":{"x-resource-group":"messages","operationId":"getCallRecording","tags":["Calls"],"summary":"Get a call recording","description":"Channel-agnostic recording fetch: resolves a fresh, playable MP3 URL\nfor any call regardless of channel (provider-signed URLs expire ~10\nminutes after signing, so this re-signs on demand). Default responds\n`302 Found` redirecting to the fresh URL; pass `as=json` to receive\n`{ url }` instead.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"as","in":"query","schema":{"type":"string","enum":["json"]},"description":"`json` returns `{ url }` instead of a 302 redirect."}],"responses":{"200":{"description":"Recording URL (`as=json` only).","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}}}}}},"302":{"description":"Redirect to a freshly-signed recording URL."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Call not found, or no recording is available for this call"},"502":{"description":"Recording provider lookup failed"}}}},"/v1/voice/calls":{"post":{"x-resource-group":"messages","operationId":"createVoiceCall","tags":["Voice"],"summary":"Place an outbound phone call","description":"Dials `to` FROM one of your voice-enabled numbers and, on answer, bridges the callee to the number's stored forward destination, or to the per-call `forwardTo` override.\n\nDestinations can be your own AI voice agent (Vapi/Retell), a phone, or a SIP endpoint. An optional `greeting` is spoken to the callee before the bridge.\n\n### Response and limits\n\nThe 200 response means the call is dialing. The lifecycle continues asynchronously: track it via `GET /v1/voice/calls/{id}` or the `call.*` webhooks.\n\nOutbound calls are capped per rolling hour (429 when hit).\n\n### Idempotency\n\nSend an `Idempotency-Key` header to make retries safe. Same key + same body replays the original response instead of dialing (and billing) a second call.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to"],"properties":{"to":{"type":"string","pattern":"^\\+\\d{6,15}$","description":"Destination to dial, E.164 with leading +."},"fromNumber":{"type":"string","pattern":"^\\+\\d{6,15}$","description":"Which of your voice-enabled numbers to dial from. Optional when you have exactly one."},"forwardTo":{"type":"string","description":"Per-call agent override (tel:+E164, sip:..., or wss://...); defaults to the number's stored forward destination."},"greeting":{"type":"string","maxLength":1000,"description":"Spoken to the callee when they answer, before the bridge."},"recordOverride":{"type":"boolean","description":"Per-call recording toggle; defaults to the number's setting."},"transcribeOverride":{"type":"boolean","description":"Per-call transcription toggle; defaults to the number's setting."},"transcriptionLanguage":{"type":"string","enum":["auto","en","es"],"description":"'auto' derives from the callee's country; 'en'/'es' force it."},"amd":{"type":"boolean","description":"Answering-machine detection; defers the bridge until human vs machine is known."},"voicemailDropMessage":{"type":"string","maxLength":1000,"description":"Spoken to a detected machine, then hang up (implies `amd`). For outbound voicemail drops."},"ringTimeoutSeconds":{"type":"integer","minimum":5,"maximum":120,"default":30,"description":"Seconds to let the callee's phone ring before the call ends as no_answer. The destination carrier can end it sooner."}}}}}},"responses":{"200":{"description":"Call originated; lifecycle continues asynchronously.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"callId":{"type":"string","description":"Internal Call doc ID"},"telnyxCallControlId":{"type":"string"},"status":{"type":"string","enum":["dialing"]},"direction":{"type":"string","enum":["outbound"]},"from":{"type":"string"},"to":{"type":"string"},"forwardTo":{"type":"string"},"greeting":{"type":["string","null"]},"recordingEnabled":{"type":"boolean"},"transcriptionEnabled":{"type":"boolean"},"transcriptionLanguage":{"type":"string","enum":["auto","en","es"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/BalanceRequired"},"422":{"description":"No voice-enabled number matches `fromNumber`, or no forward destination configured (set the number's forward or pass `forwardTo`)."},"429":{"description":"Outbound call limit reached (per rolling hour)."},"502":{"description":"Carrier-side originate failed; the call has been marked failed."}}},"get":{"x-resource-group":"messages","operationId":"listVoiceCalls","tags":["Voice"],"summary":"List phone calls","description":"Your PSTN voice calls (inbound + outbound), newest first. Cursor\npagination: pass the returned `nextCursor` as `before` for the next\npage. For a history that also includes WhatsApp calls, use\n`GET /v1/calls`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["ringing","answered","ended","failed"]}},{"name":"direction","in":"query","schema":{"type":"string","enum":["inbound","outbound"]}},{"name":"number","in":"query","schema":{"type":"string"},"description":"Exact filter: calls involving this number (typically one of your DIDs). E.164, leading + optional."},{"name":"before","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Calls, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"calls":{"type":"array","items":{"$ref":"#/components/schemas/CallRecord"}},"nextCursor":{"type":["string","null"],"format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/voice/calls/{id}":{"get":{"x-resource-group":"messages","operationId":"getVoiceCall","tags":["Voice"],"summary":"Get a phone call","description":"Full call detail, including the transcript segments when transcription was on.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Call","content":{"application/json":{"schema":{"type":"object","properties":{"call":{"$ref":"#/components/schemas/CallRecord"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Call not found"}}}},"/v1/voice/calls/{id}/end":{"post":{"x-resource-group":"messages","operationId":"endVoiceCall","tags":["Voice"],"summary":"Hang up a live call","description":"Hangs up a live call on demand, including an outbound call that is still ringing and has not been answered yet (the callee stops ringing immediately).\n\n### Supported calls\n\n- PSTN calls.\n- WhatsApp calls: the `callId` returned by `POST /v1/whatsapp/calls`, or an inbound WhatsApp call id.\n\nA WhatsApp call forwarded to a `wss://` destination also ends automatically when that WebSocket closes.\n\n### Idempotency and timing\n\nIdempotent: ending a call that already ended (or never connected) returns success with the call's current status.\n\nFinal duration/cost are written asynchronously when the hangup event lands, so the call doc may briefly still show its prior status.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Hangup issued (or the call was already over).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"callId":{"type":"string"},"status":{"type":"string","description":"`ending` when a hangup was issued; otherwise the call's current status."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Call not found"},"502":{"description":"Carrier-side hangup failed"}}}},"/v1/voice/calls/{id}/recording":{"get":{"x-resource-group":"messages","operationId":"getVoiceCallRecording","tags":["Voice"],"summary":"Get a call recording","description":"Resolves a fresh, playable MP3 URL for the call's recording\n(provider-signed URLs expire ~10 minutes after signing, so this\nendpoint re-signs on demand). Default responds `302 Found` redirecting\nto the fresh URL; pass `as=json` to receive `{ url }` instead.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"as","in":"query","schema":{"type":"string","enum":["json"]},"description":"`json` returns `{ url }` instead of a 302 redirect."}],"responses":{"200":{"description":"Recording URL (`as=json` only).","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}}}}}},"302":{"description":"Redirect to a freshly-signed recording URL."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Call not found, or no recording is available for this call"},"502":{"description":"Recording provider lookup failed"}}}},"/v1/voice/calls/{id}/transfer":{"post":{"x-resource-group":"messages","operationId":"transferVoiceCall","tags":["Voice"],"summary":"Blind-transfer a live call","description":"Moves the call's current leg to a new destination (a phone number or a SIP endpoint).\n\nThis is a BLIND transfer: control of the leg is handed off and the call ends normally when the transferred leg hangs up. The caller ID presented on the transfer leg is always your own number.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to"],"properties":{"to":{"type":"string","description":"+E164 phone number (tel: prefix optional) or a sip: URI. wss:// is not a valid transfer target."}}}}}},"responses":{"200":{"description":"Transfer issued.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"callId":{"type":"string"},"transferredTo":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Call not found"},"409":{"description":"Call is not connected yet, or has already ended"}}}},"/v1/voice/calls/estimate":{"get":{"x-resource-group":"messages","operationId":"getVoiceCallEstimate","tags":["Voice"],"summary":"Estimate call cost","description":"Pre-call cost estimate for a PSTN call: the carrier leg plus optional recording and transcription add-ons.\n\nIt uses the same billing formula as the post-call invoice, so the quote and the final charge can't disagree.\n\nThe carrier figure follows the carrier's per-destination rate card: a call dialed from a number in the destination country uses the local mobile rate, and a `tel:` forward destination is quoted as a second carrier leg billed from the same number.\n\nThe real cost comes from the settled carrier record after the call.\n\nParity endpoint of `GET /v1/whatsapp/calls/estimate`, minus the Meta line. PSTN calls have no separate Meta bill, so `totalCostUSD` equals `billableCostUSD`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"to","in":"query","required":true,"schema":{"type":"string"},"description":"Destination number, E.164 (leading + optional)."},{"name":"from","in":"query","schema":{"type":"string"},"description":"The number the call would dial from, E.164. When it is verified on a Branded Calling identity and `to` is a US number, the estimate includes the per-call Branded Calling surcharge."},{"name":"forwardTo","in":"query","schema":{"type":"string"},"description":"Destination the call bridges to: `tel:+E164`, `sip:...` or `wss://...`. Defaults to the dialing number's configured forward. A `tel:` destination adds a second carrier leg to the quote. Encode the `+` as `%2B`."},{"name":"minutes","in":"query","schema":{"type":"integer","minimum":1,"maximum":120,"default":1}},{"name":"recording","in":"query","schema":{"type":"boolean"}},{"name":"transcription","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Estimate","content":{"application/json":{"schema":{"type":"object","properties":{"destinationCountry":{"type":["string","null"]},"minutes":{"type":"integer"},"perMinuteUsd":{"type":"number","description":"Billable cost per minute for the requested options."},"breakdown":{"type":"object","properties":{"telnyxCostUSD":{"type":"number"},"recordingCostUSD":{"type":"number"},"transcriptionCostUSD":{"type":"number"},"brandedCallUSD":{"type":"number","description":"Branded Calling surcharge, 0 unless `from` is a verified branded number calling a US destination."},"billableCostUSD":{"type":"number","description":"What Zernio bills for the call."},"totalCostUSD":{"type":"number","description":"Equals billableCostUSD (no separate Meta bill on PSTN); kept for shape parity with the WhatsApp estimate."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/voice/calls/web":{"post":{"x-resource-group":"messages","operationId":"createVoiceWebSession","tags":["Voice"],"summary":"Mint a browser softphone session","description":"Step 1 of the two-step browser softphone handshake. Mints a WebRTC session (token + credential) the browser registers with the `@telnyx/webrtc` SDK.\n\n1. Call this endpoint and register the browser with the returned session.\n2. Once registered, call `POST /v1/voice/calls/web/dial` with the returned `credentialId` to place the call.\n\nThe split avoids bridging to a browser that has not finished registering. The token lives ~1 hour (it must outlive the whole call, not only the handshake).\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"WebRTC session minted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"token":{"type":"string","description":"Login token for the browser WebRTC SDK."},"credentialId":{"type":"string","description":"Pass to POST /v1/voice/calls/web/dial once the browser is registered."},"expiresAt":{"type":"string","format":"date-time"},"sdk":{"type":"string","example":"@telnyx/webrtc"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"description":"Failed to mint the WebRTC session"}}}},"/v1/voice/calls/web/dial":{"post":{"x-resource-group":"messages","operationId":"dialVoiceWebCall","tags":["Voice"],"summary":"Dial from the browser softphone","description":"Step 2 of the browser softphone handshake: rings the browser registered with the credential from `POST /v1/voice/calls/web` first, and dials the target only once the browser answers.\n\nThe callee's pickup then connects immediately, with no ringing after they answer.\n\n- The call is logged as outbound (from = your number, to = target) and recorded per the number's settings.\n- `ringTimeoutSeconds` applies to the target's phone, not to the browser.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to","credentialId"],"properties":{"to":{"type":"string","pattern":"^\\+\\d{6,15}$","description":"The number to call, E.164 with leading +."},"credentialId":{"type":"string","description":"The WebRTC credential id returned by POST /v1/voice/calls/web (the registered browser)."},"fromNumber":{"type":"string","pattern":"^\\+\\d{6,15}$","description":"Which of your voice-enabled numbers to call from (optional when you have one)."},"recordOverride":{"type":"boolean"},"ringTimeoutSeconds":{"type":"integer","minimum":5,"maximum":120,"default":30,"description":"Seconds to let the callee's phone ring before the call ends as no_answer. The destination carrier can end it sooner."}}}}}},"responses":{"200":{"description":"Call originated; answer/bridge continue asynchronously.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"callId":{"type":"string"},"telnyxCallControlId":{"type":"string"},"status":{"type":"string","enum":["dialing"]},"direction":{"type":"string","enum":["outbound"]},"from":{"type":"string"},"to":{"type":"string"},"recordingEnabled":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/BalanceRequired"},"422":{"description":"Invalid or unknown WebRTC credential, or no voice-enabled number matches `fromNumber`"},"429":{"description":"Outbound call limit reached (per rolling hour)."},"502":{"description":"Carrier-side originate failed"}}}},"/v1/imessage/senders":{"get":{"operationId":"listImessageSenders","summary":"List iMessage senders","description":"Lists the iMessage senders registered across your accessible profiles.","tags":["iMessage"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Registered iMessage senders","content":{"application/json":{"schema":{"type":"object","properties":{"senders":{"type":"array","items":{"$ref":"#/components/schemas/ImessageSender"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"operationId":"registerImessageSender","summary":"Register an iMessage sender","description":"Registers a provider-provisioned iMessage sender (a phone number or an email handle) that YOU already own on a profile. It creates an `imessage` account that sends and receives through the inbox conversation endpoints.\n\nTo have Zernio order a new sender for you, use POST /v1/imessage/senders/order instead.\n\n### Billing\n\nRegistration attaches the monthly sender fee (billed while active) and requires a payment method (402 without one).\n\n### Re-registering\n\n- Re-registering the SAME handle refreshes its account.\n- A different handle is added as another sender, and a profile can hold several.\n","tags":["iMessage"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","sender"],"properties":{"profileId":{"type":"string","description":"Profile to attach the sender to"},"sender":{"type":"string","description":"The provider-provisioned sender handle: a phone number in international format (e.g. +18305551234) or an email address"},"displayName":{"type":"string","maxLength":100},"provider":{"type":"string","enum":["loopmessage"],"description":"Delivery provider. Defaults to the platform default."}}}}}},"responses":{"200":{"description":"Sender registered","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"account":{"$ref":"#/components/schemas/ImessageSender"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"A valid payment method is required, or the last payment failed and is unpaid: pay the invoice or update the card.","description":"A valid payment method is required (code: payment_method_required), or the last payment failed and is still unpaid (code: payment_required). Pay the open invoice or update the card in Billing, then retry."},"404":{"description":"Profile not found or access denied"},"409":{"x-summary":"The sender is registered to another profile, or billing setup is incomplete and support must finish it: contact support.","description":"Sender already registered to another profile (code: imessage_sender_conflict), or billing setup is incomplete and support must finish it (code: billing_setup_incomplete)"}}}},"/v1/imessage/senders/order":{"get":{"operationId":"listImessageSenderOrders","summary":"List iMessage sender orders","description":"Every sender lifecycle doc your team owns (ordered or registered), across statuses. Canceled senders are omitted unless `includeCanceled=true`.","tags":["iMessage"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"includeCanceled","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Sender lifecycle docs, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"senders":{"type":"array","items":{"$ref":"#/components/schemas/ImessageSenderLifecycle"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"operationId":"orderImessageSender","summary":"Order a new iMessage sender","description":"Orders a NEW dedicated iMessage sender from the delivery provider. Compare with POST /v1/imessage/senders, which registers a sender you already own.\n\n### Activation\n\nActivation is asynchronous (minutes to a few hours). The response is 202 with the lifecycle object; poll GET /v1/imessage/senders/{senderId} or subscribe to the account.connected webhook.\n\n### Billing\n\n- Requires usage-based billing and a valid payment method.\n- Billing starts at activation (monthly per sender, no proration).\n- When the account spend threshold is below the sender price, the first month is charged before the number is bought.\n- When the card's answer takes longer than this request, the order is returned as `status: awaiting_payment`. The number is ordered automatically once it is paid (usually under 5 minutes).\n\n### Retries\n\nPass purchaseIntentId to make retries idempotent. The provider-side order is never retried automatically.\n\n### What an ordered sender includes\n\nOrdered phone senders include SMS/RCS fallback with call forwarding, and the ability to message contacts who have not written first (sending intervals still apply).\n","tags":["iMessage"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","kind"],"properties":{"profileId":{"type":"string"},"kind":{"type":"string","enum":["phone","email"]},"region":{"type":"string","enum":["US","GB"],"description":"Required for phone senders. Without availableNumberId the number is carrier-assigned in this region and revealed once the sender activates."},"availableNumberId":{"type":"string","description":"A number from GET /v1/imessage/senders/available-numbers. It is assigned and activated on order instead of waiting for provisioning. Phone senders only."},"zipCode":{"type":"string","pattern":"^[0-9]{5}$","description":"US phone senders only. Preferred area for a carrier-assigned number (ignored with availableNumberId)."},"emailName":{"type":"string","description":"Local part for email senders (required for kind: email)"},"emailDomain":{"type":"string","description":"Domain for email senders (required for kind: email)"},"displayName":{"type":"string","maxLength":100},"purchaseIntentId":{"type":"string","maxLength":100,"description":"Idempotency key for safe retries"},"contact":{"type":"object","description":"Contact card (vCard) attached to the sender, shown when recipients save it. Required before sending with contactCard.","required":["firstName"],"properties":{"firstName":{"type":"string","maxLength":64},"lastName":{"type":"string","maxLength":64},"photoUrl":{"type":"string","format":"uri"}}}}}}}},"responses":{"202":{"x-summary":"The order is accepted and activation continues asynchronously: poll `sender.status`, which moves on by itself from its pending states.","description":"Order accepted; activation continues asynchronously. `sender.status` is `ordering` or `activating` when the provider has the order, `awaiting_payment` while the first-month charge is still being confirmed (poll the sender; it moves on by itself).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"sender":{"$ref":"#/components/schemas/ImessageSenderLifecycle"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"A valid payment method is required, or a payment failed, and nothing was ordered: update the card in Billing, then order again.","description":"Nothing is ordered. A valid payment method is required (code: payment_method_required), the last payment failed or the first month was declined (code: payment_required), or, on balance billing, the balance is at $0 (code: insufficient_balance or usage_limit_reached). Fix it in Billing, then order again."},"403":{"description":"Sender limit reached (code: imessage_sender_limit)"},"404":{"description":"Profile not found or access denied"},"409":{"description":"Billing setup is incomplete and support must finish it (code: billing_setup_incomplete)."},"422":{"description":"Workspace is not on usage-based billing (code: usage_billing_required)"},"502":{"x-summary":"The provider rejected the order and nothing was charged, or a first month already billed is returned as account credit.","description":"The provider rejected the order. Nothing was charged, or a first month already billed is given back as account credit."}}}},"/v1/imessage/senders/{senderId}":{"get":{"operationId":"getImessageSender","summary":"Get iMessage sender status","description":"Lifecycle status of an ordered or registered sender (poll while an order activates), plus the provider's live platform health for it.","tags":["iMessage"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"senderId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sender lifecycle","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"sender":{"$ref":"#/components/schemas/ImessageSenderLifecycle"},"health":{"type":["object","null"],"description":"Provider platform health for this sender; null when the provider cannot report it.","properties":{"imessage":{"type":"string","enum":["active","degradation","outage"]},"whatsapp":{"type":"string","enum":["active","degradation","outage"]}}},"imessageLink":{"type":["string","null"],"description":"Provider-hosted opt-in page for this sender (opens Messages on any Apple device); null until the sender is active or when the provider cannot report it."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Sender not found"}}},"patch":{"operationId":"updateImessageSender","summary":"Update an iMessage sender","description":"Display name (inbox and API responses) and the contact card (vCard) recipients see when they save the sender. The contact card is what a contactCard send shares.","tags":["iMessage"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"senderId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"type":"string","maxLength":100},"contact":{"type":"object","required":["firstName"],"properties":{"firstName":{"type":"string","maxLength":64},"lastName":{"type":"string","maxLength":64},"photoUrl":{"type":"string","format":"uri","description":"Square image"}}}}}}}},"responses":{"200":{"description":"Sender updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"sender":{"$ref":"#/components/schemas/ImessageSenderLifecycle"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Sender not found"}}},"delete":{"operationId":"cancelImessageSender","summary":"Cancel an iMessage sender","description":"Cancels the sender at the provider and deactivates its messaging\naccount. Billing stops with the current month (no proration or\nrefunds, matching phone numbers). A sender still being set up\n(status ordering or activating) cannot be canceled; contact support\nto change the order.\n","tags":["iMessage"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"senderId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sender canceled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"sender":{"$ref":"#/components/schemas/ImessageSenderLifecycle"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Sender not found"},"409":{"description":"The sender is still being set up and cannot be canceled yet (code: imessage_sender_setting_up)"}}}},"/v1/imessage/audience":{"get":{"operationId":"listImessageAudience","summary":"List iMessage audience","description":"Contacts who have messaged your iMessage senders (1:1 threads), with subscription state and, for threads opened through a tracked opt-in link, the parameters that brought them in. Newest activity first.","tags":["iMessage"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":false,"schema":{"type":"string"},"description":"Limit to one sender account"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["subscribed","unsubscribed"]}},{"name":"search","in":"query","required":false,"schema":{"type":"string","maxLength":120},"description":"Matches the contact handle or name"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Audience page","content":{"application/json":{"schema":{"type":"object","properties":{"contacts":{"type":"array","items":{"$ref":"#/components/schemas/ImessageAudienceContact"}},"total":{"type":"integer"},"limit":{"type":"integer"},"skip":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/imessage/sandbox/contacts":{"get":{"operationId":"listImessageSandboxContacts","summary":"List iMessage sandbox contacts","description":"Returns the shared sandbox line and your sandbox contacts.\n\nThe sandbox lets you test iMessage without ordering a sender:\n\n1. Add your own phone or Apple ID email.\n2. Send its join code to the sandbox line from that phone.\n3. Your messages reach your inbox and webhooks.\n\n### Limits\n\n- Replies are allowed for 24 hours after each message from the contact.\n- Group chats and starting conversations are not supported.\n","tags":["iMessage"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Sandbox line and contacts","content":{"application/json":{"schema":{"type":"object","properties":{"sandbox":{"type":"object","properties":{"accountId":{"type":"string","description":"Use as accountId to reply from the sandbox line"},"handle":{"type":"string","description":"The sandbox line to message"},"contactLimit":{"type":"integer"}}},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/ImessageSandboxContact"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Your plan does not include the inbox"},"404":{"description":"The sandbox is not available right now"}}},"post":{"operationId":"addImessageSandboxContact","summary":"Add an iMessage sandbox contact","description":"Adds your own phone (E.164) or Apple ID email. The contact starts as pending; it becomes active when its joinText arrives at the sandbox line from that handle (joinLink opens Messages with it prefilled). Adding a handle that is already on your list returns it unchanged.","tags":["iMessage"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["handle"],"properties":{"handle":{"type":"string","description":"Phone in international format (+15551234567) or an Apple ID email"}}}}}},"responses":{"201":{"description":"Contact added","content":{"application/json":{"schema":{"type":"object","properties":{"contact":{"$ref":"#/components/schemas/ImessageSandboxContact"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Your plan does not include the inbox"},"404":{"description":"The sandbox is not available right now"},"409":{"description":"Contact limit reached, or the handle is on someone else's sandbox list"}}}},"/v1/imessage/sandbox/contacts/{contactId}":{"delete":{"operationId":"removeImessageSandboxContact","summary":"Remove an iMessage sandbox contact","description":"Removes the contact and its sandbox conversation. Messages from that handle to the sandbox line are no longer delivered to you.","tags":["iMessage"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"contactId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Sandbox contact not found"}}}},"/v1/imessage/audience/subscription":{"post":{"operationId":"setImessageSubscription","summary":"Subscribe or opt out an iMessage contact","description":"Opted-out contacts are refused at send time (409 recipient_opted_out) until re-subscribed. Their inbound messages still arrive. Scoped to your account: it does not change the contact's state with other businesses.","tags":["iMessage"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","conversationId","subscribed"],"properties":{"accountId":{"type":"string"},"conversationId":{"type":"string"},"subscribed":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"conversationId":{"type":"string"},"subscribed":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account or conversation not found"}}}},"/v1/imessage/senders/{senderId}/opt-in-links":{"post":{"operationId":"createImessageOptInLink","summary":"Create a tracked iMessage opt-in link","description":"Generates a per-campaign link that opens Messages on this sender with `body` prefilled.\n\n### Why use it\n\nA thread the contact opens skips the pacing and the first-message content rule that apply when the sender writes first.\n\nIt is also the only way in for senders without the add-on for new contacts. Their sends to anyone else fail with `recipient_must_message_first`.\n\n### Attribution\n\nEach link carries a unique code in place of the `[opt-in-code]` placeholder. When the contact sends it, the resulting `message.received` webhook (and the stored inbox message's `metadata`) has `optIn: true` and your `parameters` under `optInParameters`.\n\nThat lets you attribute the conversation to the campaign or lead that produced it.\n\nFor an untracked link, use the sender's `optInLink` instead.\n","tags":["iMessage"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"senderId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","maxLength":500,"description":"Prefilled message text. Must contain the literal `[opt-in-code]` placeholder, e.g. \"Hi! My code is [opt-in-code]\"."},"parameters":{"type":"object","additionalProperties":{"type":"string"},"description":"Custom key/values (e.g. leadId, campaign) echoed back on the opt-in message."},"optInCode":{"type":"string","minLength":3,"maxLength":8,"description":"Your own code in place of the generated one (3-8 characters, no spaces or `#`, `!`, `-`). An unredeemed link lives 24 hours; re-issuing with the same code replaces it, and the earlier URL stops matching."}}}}}},"responses":{"200":{"description":"Opt-in link created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"link":{"type":"object","properties":{"id":{"type":"string"},"imessage":{"type":"string","description":"imessage:// deep link"},"sms":{"type":["string","null"],"description":"sms: deep link for non-Apple devices"},"whatsapp":{"type":["string","null"]},"url":{"type":"string","description":"Hosted landing URL that picks the right scheme for the device"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Sender not found"},"409":{"description":"The sender is not active yet"}}}},"/v1/imessage/senders/available-numbers":{"get":{"operationId":"listImessageAvailableNumbers","summary":"List instantly available iMessage numbers","description":"Phone numbers the provider has already registered and can assign on the spot.\n\n### Ordering one\n\n1. Reserve it first with POST /v1/imessage/senders/available-numbers/{numberId}/reserve while the buyer decides.\n2. Pass its `id` as `availableNumberId` to POST /v1/imessage/senders/order.\n\nThe sender activates immediately instead of after the usual provisioning wait.\n\nThe list is a snapshot; a number can be taken between listing and ordering.\n","tags":["iMessage"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"region","in":"query","required":false,"schema":{"type":"string","enum":["US","GB"]}}],"responses":{"200":{"description":"Available numbers","content":{"application/json":{"schema":{"type":"object","properties":{"numbers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Pass as availableNumberId when ordering"},"phone":{"type":"string","description":"E.164"},"region":{"type":"string"},"location":{"type":"string","description":"Area the provider reports for the number (e.g. a US state), when known"}}}},"region":{"type":["string","null"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"description":"The provider could not list numbers; ordering without availableNumberId still works"}}}},"/v1/imessage/senders/available-numbers/{numberId}/reserve":{"post":{"operationId":"reserveImessageAvailableNumber","summary":"Reserve an available iMessage number","description":"Holds the number for 3 minutes so nobody else can order it while the buyer decides. Place the order (POST /v1/imessage/senders/order with availableNumberId) before the hold expires. No request body.","tags":["iMessage"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"numberId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Number reserved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"numberId":{"type":"string"},"expiresInSeconds":{"type":"integer","example":180}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"description":"The number could not be reserved (already taken)"}}}},"/v1/imessage/groups":{"post":{"operationId":"createImessageGroup","summary":"Start an iMessage group chat","description":"Creates a group chat from one of your senders and sends its first message.\n\nThe provider processes it asynchronously: the response carries the request id, and the thread appears in the inbox (with its group conversation id) on the first webhook.\n\n### Requirements\n\n- Starting a group counts as messaging new contacts, so the sender needs the provider's init-conversations add-on and the same sending intervals apply. Without it the request fails with 409 `recipient_must_message_first`.\n- WhatsApp groups need a `name`.\n","tags":["iMessage"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","contacts","text"],"properties":{"accountId":{"type":"string","description":"The iMessage account (sender) that opens the group"},"contacts":{"type":"array","minItems":2,"maxItems":32,"items":{"type":"string"},"description":"Participant handles (E.164 phones or iMessage emails)"},"text":{"type":"string","maxLength":10000,"description":"The first message"},"name":{"type":"string","maxLength":32,"description":"Group name (required for WhatsApp groups)"},"channel":{"type":"string","enum":["imessage","sms","rcs","whatsapp"],"default":"imessage"}}}}}},"responses":{"202":{"description":"Group creation accepted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"requestId":{"type":"string","description":"The provider's request id (not the group id)"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found"},"409":{"description":"The sender cannot start conversations (code: recipient_must_message_first)"}}}},"/v1/imessage/groups/{conversationId}":{"get":{"operationId":"getImessageGroup","summary":"Get an iMessage group","description":"The group's name, participants and channel as the provider currently sees them. The conversation must be a group thread of the given account.","tags":["iMessage"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"The inbox conversation id (or the provider group id)"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Group details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"conversationId":{"type":"string"},"group":{"type":"object","properties":{"id":{"type":"string","description":"Provider group id"},"name":{"type":["string","null"]},"participants":{"type":"array","items":{"type":"string"}},"channel":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"}}}}}}}},"400":{"description":"Bad request, or the conversation is not a group thread"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account or conversation not found"}}},"patch":{"operationId":"updateImessageGroup","summary":"Rename an iMessage group or change its photo","description":"One change per call: either `name` or `photoUrl` (an empty `photoUrl` removes the photo). Applied asynchronously by the provider; a rename is mirrored on the inbox conversation right away.","tags":["iMessage"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string"},"name":{"type":"string","maxLength":32},"photoUrl":{"type":"string","description":"Public HTTPS image URL; empty string removes the photo"}}}}}},"responses":{"200":{"description":"Change accepted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"conversationId":{"type":"string"}}}}}},"400":{"description":"Bad request, or the conversation is not a group thread"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account or conversation not found"}}}},"/v1/imessage/groups/{conversationId}/participants":{"post":{"operationId":"addImessageGroupParticipant","summary":"Add a participant to an iMessage group","description":"Applied asynchronously by the provider; the participant list on the next group webhook reflects it.","tags":["iMessage"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","contact"],"properties":{"accountId":{"type":"string"},"contact":{"type":"string","description":"E.164 phone or iMessage email"}}}}}},"responses":{"200":{"description":"Change accepted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"conversationId":{"type":"string"},"contact":{"type":"string"}}}}}},"400":{"description":"Bad request, or the conversation is not a group thread"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account or conversation not found"}}},"delete":{"operationId":"removeImessageGroupParticipant","summary":"Remove a participant from an iMessage group","description":"Applied asynchronously by the provider.","tags":["iMessage"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"contact","in":"query","required":true,"schema":{"type":"string"},"description":"E.164 phone or iMessage email"}],"responses":{"200":{"description":"Change accepted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"conversationId":{"type":"string"},"contact":{"type":"string"}}}}}},"400":{"description":"Bad request, or the conversation is not a group thread"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account or conversation not found"}}}},"/v1/sms/messages":{"post":{"x-resource-group":"messages","operationId":"sendSms","tags":["SMS"],"summary":"Send an SMS/MMS","description":"Sends an SMS (or MMS when `mediaUrls` is set) from one of your\nSMS-enabled numbers. At least one of `text` / `mediaUrls` is required.\nBoth numbers are normalized to E.164, so `from` matches regardless of\nformatting and replies thread into the same inbox conversation.\n\nUS numbers must have an approved carrier registration\n(`/v1/sms/registrations`) before messages deliver.\n\n**Replies and delivery status arrive as webhooks**, not by polling:\nan inbound reply fires `message.received` with `platform: \"sms\"`, the\nfirst message of a new thread also fires `conversation.started`, and\nthis message's own outcome fires `message.delivered` or\n`message.failed` (the latter carrying the carrier's error code).\n\n**Opted-out recipients:** a send to a number that replied STOP is\nrefused with `409`, never silently dropped.\n\n**Idempotency:** send an `Idempotency-Key` header to make retries safe:\nsame key + same body replays the original response instead of sending a\nsecond message; same key + different body returns 422; a key still in\nflight returns 409.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string","description":"One of your SMS-enabled numbers (E.164; formatting is normalized)."},"to":{"type":"string","description":"Recipient number (E.164)."},"text":{"type":"string","description":"Message body. Required unless `mediaUrls` is set. Max 10 SMS segments (1530 GSM-7 or 670 unicode characters)."},"mediaUrls":{"type":"array","maxItems":10,"items":{"type":"string","format":"uri"},"description":"Public media URLs to attach (sends as MMS). Max 10."},"sendAt":{"type":"string","format":"date-time","description":"Optional. Schedule the send for a future time (ISO 8601 with offset, e.g. `2026-08-01T12:00:00Z`). Must be in the future. The message is queued and the `message.delivered` webhook fires when it actually sends."}}}}}},"responses":{"200":{"description":"Message accepted for delivery.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Message ID"},"conversationId":{"type":"string","description":"Inbox conversation the message was threaded into."},"status":{"type":"string","enum":["sent"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is profile-scoped and `from` belongs to a profile outside its scope (alphanumeric sender IDs included)"},"404":{"description":"No SMS-enabled number matches `from`"},"409":{"description":"Recipient has opted out (replied STOP), or the same Idempotency-Key is still in flight"},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"},"502":{"description":"Carrier-side send failed"}}}},"/v1/rcs/brands":{"get":{"x-resource-group":"messages","operationId":"listRcsBrands","tags":["RCS"],"summary":"List RCS brands","description":"The team's RCS brands (vetted companies), to reuse one for another agent with `brandId`.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Brands, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"brands":{"type":"array","items":{"$ref":"#/components/schemas/RcsBrand"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Your plan does not include the inbox, which RCS requires."}}}},"/v1/rcs/agents":{"get":{"x-resource-group":"messages","operationId":"listRcsAgents","tags":["RCS"],"summary":"List RCS agents","security":[{"bearerAuth":[]}],"parameters":[{"name":"includeClosed","in":"query","schema":{"type":"boolean"},"description":"Include rejected and deactivated agents."}],"responses":{"200":{"description":"Agents, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/RcsAgent"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Your plan does not include the inbox, which RCS requires."}}},"post":{"x-resource-group":"messages","operationId":"createRcsAgent","tags":["RCS"],"summary":"Request an RCS agent","description":"Requests a new agent for a profile, with a new company (`brand`) or an existing one (`brandId`, skips vetting when it is already verified). A profile can hold several agents.\n\nThe request lands in our review: nothing is filed with the carriers or billed until we submit it.\n\n- Requires usage-based billing and a card on file.\n- Send an `Idempotency-Key` header to make retries safe.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","displayName","useCase","profile"],"description":"Send exactly one of brandId or brand.","properties":{"profileId":{"type":"string"},"brandId":{"type":"string"},"brand":{"$ref":"#/components/schemas/RcsBrandInput"},"displayName":{"type":"string","maxLength":40,"description":"Shown as the sender name."},"useCase":{"type":"string","enum":["MULTI_USE","PROMOTIONAL","TRANSACTIONAL","OTP"]},"profile":{"$ref":"#/components/schemas/RcsAgentProfile"},"smsFallbackFrom":{"type":"string","description":"One of your SMS-enabled numbers. Phones without RCS get the message as SMS from it."}}}}}},"responses":{"201":{"description":"Agent requested.","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/RcsAgent"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"No payment method is on file: add a card and retry.","description":"No payment method on file (payment_method_required). Add a card and retry."},"403":{"description":"Your plan does not include the inbox, which RCS requires."},"404":{"description":"Profile or brand not found"},"409":{"description":"The brand was rejected, or the Idempotency-Key is still in flight"},"422":{"description":"Usage-based billing is not enabled for the workspace (USAGE_BILLING_REQUIRED), or the Idempotency-Key was reused with a different body"}}}},"/v1/rcs/agents/{agentId}":{"get":{"x-resource-group":"messages","operationId":"getRcsAgent","tags":["RCS"],"summary":"Get an RCS agent","security":[{"bearerAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The agent with its brand, carrier approvals and test devices.","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/RcsAgent"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Your plan does not include the inbox, which RCS requires."},"404":{"description":"Agent not found"}}},"patch":{"x-resource-group":"messages","operationId":"updateRcsAgent","tags":["RCS"],"summary":"Update an RCS agent","description":"Edits the filing while the agent is `requested` or `changes_requested`; answering a change\nrequest puts it back in our review. The company can only change until it is filed.\n`smsFallbackFrom` stays editable in any status (null removes it).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"displayName":{"type":"string","maxLength":40},"useCase":{"type":"string","enum":["MULTI_USE","PROMOTIONAL","TRANSACTIONAL","OTP"]},"profile":{"$ref":"#/components/schemas/RcsAgentProfile"},"brand":{"$ref":"#/components/schemas/RcsBrandInput"},"smsFallbackFrom":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"The updated agent.","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/RcsAgent"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Your plan does not include the inbox, which RCS requires."},"404":{"description":"Agent not found"},"409":{"description":"The filing is locked because it is already with the carriers"}}},"delete":{"x-resource-group":"messages","operationId":"deactivateRcsAgent","tags":["RCS"],"summary":"Deactivate an RCS agent","description":"Stops sending, disconnects its inbox account and stops monthly billing. Fees already charged are not refunded.","security":[{"bearerAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The deactivated agent.","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/RcsAgent"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Your plan does not include the inbox, which RCS requires."},"404":{"description":"Agent not found"},"409":{"description":"The agent is already rejected or deactivated"}}}},"/v1/rcs/agents/{agentId}/launch-request":{"post":{"x-resource-group":"messages","operationId":"requestRcsAgentLaunch","tags":["RCS"],"summary":"Send the launch filing","description":"Sends the launch details the carriers review (campaign, consent and a public test video).\n\n### When to send\n\n- **US agents**: send them once they are in `testing`. We review them before they reach the carriers.\n- **Other markets**: send them while still in review (`requested`, `changes_requested` or `brand_vetting`), because we file everything with the carriers at once. This saves the details without changing the status.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RcsLaunchRequest"}}}},"responses":{"200":{"description":"The agent, now in launch_review.","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/RcsAgent"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Your plan does not include the inbox, which RCS requires."},"404":{"description":"Agent not found"},"409":{"description":"The agent is not in testing"}}}},"/v1/rcs/agents/{agentId}/test-devices":{"get":{"x-resource-group":"messages","operationId":"listRcsTestDevices","tags":["RCS"],"summary":"List RCS test phones","security":[{"bearerAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Invited test phones.","content":{"application/json":{"schema":{"type":"object","properties":{"testDevices":{"type":"array","items":{"$ref":"#/components/schemas/RcsTestDevice"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Your plan does not include the inbox, which RCS requires."},"404":{"description":"Agent not found"}}},"post":{"x-resource-group":"messages","operationId":"addRcsTestDevice","tags":["RCS"],"summary":"Invite an RCS test phone","description":"Invites a phone to try the agent before launch. It must accept the invite in its\nmessaging app. Available once the agent exists with the carriers (after brand vetting).\nT-Mobile and AT&T numbers cannot be test phones.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phoneNumber"],"properties":{"phoneNumber":{"type":"string","description":"E.164"}}}}}},"responses":{"201":{"description":"Invite sent.","content":{"application/json":{"schema":{"type":"object","properties":{"testDevice":{"$ref":"#/components/schemas/RcsTestDevice"}}}}}},"400":{"description":"Invalid phone number, or the carrier refused it as a test phone"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Your plan does not include the inbox, which RCS requires."},"404":{"description":"Agent not found"},"409":{"description":"The agent does not exist with the carriers yet"}}}},"/v1/rcs/agents/{agentId}/test-devices/{testDeviceId}":{"delete":{"x-resource-group":"messages","operationId":"removeRcsTestDevice","tags":["RCS"],"summary":"Remove an RCS test phone","security":[{"bearerAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"testDeviceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Removed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Your plan does not include the inbox, which RCS requires."},"404":{"description":"Agent or test phone not found"}}}},"/v1/rcs/assets":{"post":{"x-resource-group":"messages","operationId":"uploadRcsAsset","tags":["RCS"],"summary":"Upload an RCS logo or banner","description":"Uploads an image and returns a public URL for `profile.logoUrl` or `profile.heroUrl`.\nThe image is cropped and compressed to the carriers' exact rules (logo 224x224 under\n50 KB, banner 1440x448 under 200 KB).\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","kind"],"properties":{"file":{"type":"string","format":"binary","description":"PNG, JPEG or WebP."},"kind":{"type":"string","enum":["logo","banner"]}}}}}},"responses":{"200":{"description":"Hosted URL.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Your plan does not include the inbox, which RCS requires."},"422":{"description":"The image is unreadable, too small, or could not be compressed under the limit"}}}},"/v1/rcs/messages":{"post":{"x-resource-group":"messages","operationId":"sendRcsMessage","tags":["RCS"],"summary":"Send an RCS message","description":"Sends an RCS message from one of your agents.\n\n- Use `text` for a plain message or `content` for rich content (card, carousel, media, suggestion chips).\n- Before launch an agent only reaches test phones that accepted the invite.\n- With the agent's `smsFallbackFrom` set, phones without RCS get `fallbackText` (default: the message's readable text) as SMS.\n\nSend an `Idempotency-Key` header to make retries safe.\n\n### Webhooks\n\nReplies and status arrive as webhooks with `platform: \"rcs\"`:\n\n- `message.received` (a tapped chip carries its postback in `metadata.postbackPayload`)\n- `message.delivered`\n- `message.read`\n- `message.failed`\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentId","to"],"description":"Send exactly one of text or content.","properties":{"agentId":{"type":"string"},"to":{"type":"string","description":"Recipient number (E.164; formatting is normalized)."},"text":{"type":"string","maxLength":3072},"content":{"$ref":"#/components/schemas/RcsContent"},"fallbackText":{"type":"string","maxLength":3072},"ttlSeconds":{"type":"integer","minimum":1,"description":"Seconds before an undelivered message expires."}}}}}},"responses":{"200":{"description":"Message accepted.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Message ID"},"conversationId":{"type":"string"},"status":{"type":"string","enum":["sent"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The plan does not include the inbox, the recipient is not an accepted test phone before launch, or usage billing is not enabled"},"404":{"description":"Agent not found"},"409":{"description":"The agent cannot send yet, the recipient opted out (replied STOP), or the Idempotency-Key is still in flight"},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"},"502":{"description":"Carrier-side send failed"}}}},"/v1/rcs/capabilities":{"get":{"x-resource-group":"messages","operationId":"getRcsCapabilities","tags":["RCS"],"summary":"Check RCS capability","description":"Which recipients can receive RCS from the agent and which rich features their phones support. Up to 100 numbers.","security":[{"bearerAuth":[]}],"parameters":[{"name":"agentId","in":"query","required":true,"schema":{"type":"string"}},{"name":"numbers","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated E.164 numbers, max 100."}],"responses":{"200":{"description":"One entry per number, in input order.","content":{"application/json":{"schema":{"type":"object","properties":{"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/RcsCapability"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Your plan does not include the inbox, which RCS requires."},"404":{"description":"Agent not found"},"409":{"description":"The agent does not exist with the carriers yet"}}}},"/v1/sms/lookup":{"get":{"x-resource-group":"telephony","operationId":"lookupSmsNumber","tags":["SMS"],"summary":"Look up carrier + line type","description":"Carrier name and line type (mobile / landline / voip / toll-free) for a\nnumber, plus `smsReachable`. Use it to\nvalidate recipients before sending. Each lookup is billed by the\ncarrier-data provider, so call it explicitly (e.g. pre-validating an\nopt-in list), not on every send.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"number","in":"query","required":true,"schema":{"type":"string","minLength":8},"description":"Number to look up (E.164; formatting is normalized)."}],"responses":{"200":{"x-summary":"The lookup succeeded: an unknown or invalid number returns a `lineType` of unknown and no SMS reachability instead of an error.","description":"Lookup result. An unknown/invalid number returns lineType `unknown` with `smsReachable` false rather than an error.","content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumber":{"type":"string"},"carrierName":{"type":["string","null"]},"lineType":{"type":"string","enum":["mobile","landline","voip","toll-free","unknown"]},"smsReachable":{"type":"boolean","description":"False for landlines, toll-free numbers, ambiguous fixed-or-mobile lines and carriers whose numbers are not SMS-routable. True is a best guess, not a delivery guarantee."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"description":"Lookup provider failed"}}}},"/v1/sms/opt-outs":{"get":{"x-resource-group":"contacts","operationId":"listSmsOptOuts","tags":["SMS"],"summary":"List SMS opt-outs","description":"The recipients who opted out of SMS (replied STOP) across your numbers,\nmost recent first. Compliance surface: you must be able to see and\nexport your opt-out list. Read-only: a recipient is re-subscribed only\nby replying START. Pass `format=csv` to download a CSV instead of JSON.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"],"default":"json"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":5000,"default":500}}],"responses":{"200":{"description":"Opt-out list","content":{"application/json":{"schema":{"type":"object","properties":{"optOuts":{"type":"array","items":{"type":"object","properties":{"phoneNumber":{"type":"string"},"optedOutAt":{"type":["string","null"],"format":"date-time"},"keyword":{"type":["string","null"],"description":"The keyword they sent (e.g. STOP), when the carrier recorded one."},"from":{"type":["string","null"],"description":"Which of your numbers the recipient opted out from."}}}},"count":{"type":"integer"}}}},"text/csv":{"schema":{"type":"string","description":"`format=csv` download. Columns: phone_number, opted_out_at, keyword, our_number"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/sms/sender-ids":{"post":{"x-resource-group":"telephony","operationId":"createSmsSenderId","tags":["SMS"],"summary":"Create an alphanumeric sender ID","description":"Registers an alphanumeric sender ID (e.g. `ZERNIO`), a branded `from` for one-way international SMS.\n\nNo phone number purchase or carrier registration is needed. Once created, pass it as `from` on `POST /v1/sms/messages`.\n\n### Constraints\n\n- 3-11 characters (letters, digits, spaces; at least one letter).\n- Sends cannot reach the US, Canada, or Puerto Rico.\n- Sends are text-only, and recipients cannot reply.\n- Sender IDs that impersonate well-known brands or institutions are rejected.\n\n### Uniqueness\n\nNames are not exclusive: the same sender ID can be registered by any number of teams. Creating the same sender ID again is a no-op (re-activates it after a delete).\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["senderId"],"properties":{"senderId":{"type":"string","minLength":3,"maxLength":11,"description":"The sender ID recipients will see (3-11 letters/digits/spaces, at least one letter, no leading/trailing space)."}}}}}},"responses":{"200":{"description":"Sender ID created (or re-activated).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Sender ID resource id."},"senderId":{"type":"string"},"isActive":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"No payment method is on file, and Sender ID sends incur carrier fees: the billing owner must add a card first.","description":"No payment method on file (code `payment_required`). Sender-ID sends incur carrier fees, so the billing owner needs a card before one can be created."},"403":{"x-summary":"The team is not on usage-based billing, or already holds the maximum of 1,000 active sender IDs: contact support to raise it.","description":"The team is not on usage-based billing, or already holds the maximum of 1,000 active sender IDs (code `sender_id_limit_reached`; raisable via support)."},"409":{"description":"Billing setup is incomplete for this team (code `billing_setup_incomplete`); contact support."},"422":{"description":"Sender ID rejected: it appears to impersonate a protected brand or institution."}}},"get":{"x-resource-group":"telephony","operationId":"listSmsSenderIds","tags":["SMS"],"summary":"List alphanumeric sender IDs","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The team's sender IDs, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"senderIds":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"senderId":{"type":"string"},"isActive":{"type":"boolean"},"createdAt":{"type":["string","null"],"format":"date-time"}}}},"budget":{"type":"object","description":"Team-wide daily sending budget, shared by every sender ID (resets midnight UTC).","properties":{"cap":{"type":"integer","description":"Daily message cap (raisable via `/v1/sms/sender-ids/limit-request`)."},"usedToday":{"type":"integer","description":"Messages already counted against today's cap."},"level":{"type":"integer","description":"Cap tier (Level 1 = 500/day)."},"pendingRequest":{"type":["object","null"],"description":"The in-flight cap-raise request awaiting review, or null. While set, further requests return 409.","properties":{"requestedCap":{"type":"integer"},"level":{"type":"integer"},"requestedAt":{"type":["string","null"],"format":"date-time"}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/sms/sender-ids/limit-request":{"post":{"x-resource-group":"telephony","operationId":"requestSmsSenderIdLimitIncrease","tags":["SMS"],"summary":"Request a higher sender ID daily limit","description":"Asks support to raise the team's daily sender-ID message cap.\nThere is no self-serve raise: the request (desired cap + use case) is\nreviewed manually, usually within a business day.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["requestedCap","reason"],"properties":{"requestedCap":{"type":"integer","description":"Desired daily message cap. Must exceed the current cap."},"reason":{"type":"string","minLength":10,"maxLength":2000,"description":"Use case and audience (what you send, to whom, opt-in status)."}}}}}},"responses":{"200":{"description":"Request submitted for review.","content":{"application/json":{"schema":{"type":"object","properties":{"requested":{"type":"boolean"},"requestedCap":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"description":"A cap-raise request is already awaiting review (code `sender_id_raise_pending`); one at a time."},"503":{"description":"Request could not be submitted; retry or contact support."}}}},"/v1/sms/sender-ids/{id}":{"delete":{"x-resource-group":"telephony","operationId":"deleteSmsSenderId","tags":["SMS"],"summary":"Delete an alphanumeric sender ID","description":"Deactivates the sender ID so it can no longer send. Re-creating the\nsame sender ID via `POST /v1/sms/sender-ids` re-activates it.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Sender ID resource id."}],"responses":{"200":{"description":"Sender ID deactivated.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Sender ID not found."}}}},"/v1/branded-calling/enterprises":{"post":{"x-resource-group":"telephony","operationId":"createBrandedCallingEnterprise","tags":["Branded Calling"],"summary":"Register a business for Branded Calling","description":"Stores the legal entity behind your caller identities. Nothing is filed with the carrier until the business's first identity passes review.\n\nOnly businesses registered in the US or Canada qualify (a FEIN or Canadian equivalent is required); any other country returns `422`.\n\nSend an `Idempotency-Key` so a retry replays the original response instead of registering the business twice.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["legalName","doingBusinessAs","organizationType","organizationLegalType","countryCode","jurisdictionOfIncorporation","website","fein","industry","numberOfEmployees","organizationContact","billingContact","physicalAddress","billingAddress"],"properties":{"legalName":{"type":"string","minLength":3,"maxLength":64,"description":"Exactly as on the tax record."},"doingBusinessAs":{"type":"string","maxLength":255},"organizationType":{"type":"string","enum":["commercial","government","non_profit"]},"organizationLegalType":{"type":"string","enum":["corporation","llc","partnership","nonprofit","other"]},"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2. US or CA."},"jurisdictionOfIncorporation":{"type":"string","maxLength":255,"description":"State, province or country of registration."},"website":{"type":"string","format":"uri"},"fein":{"type":"string","description":"US Federal Employer Identification Number (NN-NNNNNNN) or the Canadian equivalent. Stored encrypted; only the last four digits are ever returned."},"industry":{"type":"string","description":"One of the carrier industry labels, e.g. technology, healthcare, retail, finance, legal, insurance, real estate, logistics, education."},"numberOfEmployees":{"type":"string","enum":["1-10","11-50","51-200","201-500","501-2000","2001-10000","10001+"]},"organizationContact":{"$ref":"#/components/schemas/BrandedCallingContact"},"billingContact":{"$ref":"#/components/schemas/BrandedCallingContact"},"physicalAddress":{"$ref":"#/components/schemas/BrandedCallingAddress"},"billingAddress":{"$ref":"#/components/schemas/BrandedCallingAddress"}}}}}},"responses":{"201":{"description":"Business stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandedCallingEnterprise"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/IdempotencyKeyInFlight"},"422":{"x-summary":"The business is not registered in the US or Canada, or the Idempotency-Key was reused with a different body: fix the request.","description":"The business is not registered in the US or Canada (code feature_not_available), or the Idempotency-Key was reused with a different body (code idempotency_key_reused)."}}},"get":{"x-resource-group":"telephony","operationId":"listBrandedCallingEnterprises","tags":["Branded Calling"],"summary":"List registered businesses","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The workspace's businesses.","content":{"application/json":{"schema":{"type":"object","properties":{"enterprises":{"type":"array","items":{"$ref":"#/components/schemas/BrandedCallingEnterprise"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/branded-calling/enterprises/{id}":{"get":{"x-resource-group":"telephony","operationId":"getBrandedCallingEnterprise","tags":["Branded Calling"],"summary":"Get a registered business","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandedCallingEnterprise"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Business not found"}}},"delete":{"x-resource-group":"telephony","operationId":"deleteBrandedCallingEnterprise","tags":["Branded Calling"],"summary":"Delete a registered business","description":"Refused while the business still has caller identities (delete those first).","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["deleted"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Business not found"},"409":{"description":"The business still has caller identities (code invalid_resource_state)."}}}},"/v1/branded-calling/share":{"post":{"x-resource-group":"telephony","operationId":"shareBrandedCallingIdentityForm","tags":["Branded Calling"],"summary":"Create a caller identity share link","description":"Creates a single-use link (valid 7 days) where the end business fills in the caller identity itself, with no Zernio login. It covers display name, logo, call reasons, the authorizer and the three references.\n\nWhat it submits lands under your team as `requested`, the same review as an API submission, and `branded_calling.identity.status_updated` fires.\n\n### Scoping the link\n\n- `identityId`: complete an identity that is `requested` or `changes_requested`.\n- `enterpriseId`: a new identity for a registered business.\n- Neither: the business registers itself and its first identity.\n\nThe person opening the link can forward a fresh one to someone else, which retires theirs.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"enterpriseId":{"type":"string","description":"A registered business the identity belongs to."},"identityId":{"type":"string","description":"An identity in review to complete. Not with enterpriseId."}}}}}},"responses":{"200":{"description":"Share link created.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Business or identity not found, or the identity is not in review"}}}},"/v1/branded-calling/call-reasons":{"get":{"x-resource-group":"telephony","operationId":"listBrandedCallingCallReasons","tags":["Branded Calling"],"summary":"List pre-approved call reasons","description":"The carrier catalogue of call reasons that pass vetting automatically. Any other wording is allowed on an identity but is vetted by hand.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The catalogue.","content":{"application/json":{"schema":{"type":"object","properties":{"callReasons":{"type":"array","items":{"type":"string"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/branded-calling/identities":{"post":{"x-resource-group":"telephony","operationId":"createBrandedCallingIdentity","tags":["Branded Calling"],"summary":"Create a caller identity","description":"Creates a caller identity: what the callee sees (display name, logo and call reasons). It is backed by a registered business and three references the carrier vetting team phones.\n\n### Lifecycle\n\n1. It starts in Zernio review (`requested`).\n2. Once approved, the carrier emails the authorizer a 6-digit code.\n3. Confirm the code with the verify-email endpoint, and the identity goes into carrier vetting on its own.\n\nTrack it with `GET` or the `branded_calling.identity.status_updated` webhook.\n\n### Billing\n\n- $100 per identity per month while it is verified.\n- The first month is charged when the carrier verifies the identity, never when it is filed. Nothing is charged while it is in our review or carrier vetting, or if it is rejected.\n- An edit that sends a verified identity back to vetting pauses the fee until it is verified again.\n- Branded calls add $0.10 each, counted on every outbound call from a verified branded number to a US destination (whether or not the callee's carrier displayed the branding).\n\nThe surcharge shows as `brandedCallUSD` on the call's billing and in `GET /v1/voice/calls/estimate` when you pass `from`.\n\n### Before you file\n\nRun `POST /v1/branded-calling/identities/preflight` with the same body first to catch what the review would bounce.\n\nSend an `Idempotency-Key` so a retry replays the original response instead of creating a second identity.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["enterpriseId","displayName","callReasons","authorizer","references"],"properties":{"enterpriseId":{"type":"string","description":"A business from POST /v1/branded-calling/enterprises."},"displayName":{"type":"string","minLength":1,"maxLength":35,"description":"Shown on the callee's screen. No emoji."},"callReasons":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","maxLength":64},"description":"1 to 10 reasons you call, each up to 64 characters. Pick from GET /v1/branded-calling/call-reasons to skip manual vetting."},"logoUrl":{"type":"string","description":"HTTPS URL of a PNG, JPEG, WebP or SVG logo. Zernio converts it to the 256x256 BMP the carriers require and hosts it."},"authorizer":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string","maxLength":255,"description":"A real person at the business who authorizes the registration."},"email":{"type":"string","format":"email","description":"The carrier emails a 6-digit code here once the identity passes review."}}},"references":{"$ref":"#/components/schemas/BrandedCallingReferences"}}}}}},"responses":{"201":{"description":"Identity created, in review.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandedCallingIdentity"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/BalanceRequired"},"403":{"description":"Usage-based billing is required (code usage_billing_required)."},"404":{"description":"Business not found"},"409":{"$ref":"#/components/responses/IdempotencyKeyInFlight"},"422":{"description":"The logo could not be downloaded or is not an image, or the Idempotency-Key was reused with a different body (code idempotency_key_reused)."}}},"get":{"x-resource-group":"telephony","operationId":"listBrandedCallingIdentities","tags":["Branded Calling"],"summary":"List caller identities","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The workspace's identities with their numbers.","content":{"application/json":{"schema":{"type":"object","properties":{"identities":{"type":"array","items":{"$ref":"#/components/schemas/BrandedCallingIdentity"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/branded-calling/identities/preflight":{"post":{"x-resource-group":"telephony","operationId":"preflightBrandedCallingIdentity","tags":["Branded Calling"],"summary":"Dry-run a caller identity before creating it","description":"Validates the exact body `POST /v1/branded-calling/identities` takes and runs the same deterministic lints the review runs on it, without creating anything. Findings carry the same codes and fields as the queued identity's findings.\n\n### Finding levels\n\n- `block`: what the review would bounce. Examples: two references sharing a phone, a reference inside the business, an invalid timezone.\n- `warn`: slows vetting. Examples: a display name that does not read as the business, a call reason outside the carrier catalogue, a public-mailbox authorizer, a logo that does not answer.\n\n`ok` is true when there is no `block`.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["enterpriseId","displayName","callReasons","authorizer","references"],"description":"Same body as createBrandedCallingIdentity.","properties":{"enterpriseId":{"type":"string"},"displayName":{"type":"string","minLength":1,"maxLength":35},"callReasons":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","maxLength":64}},"logoUrl":{"type":"string"},"authorizer":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string","maxLength":255},"email":{"type":"string","format":"email"}}},"references":{"$ref":"#/components/schemas/BrandedCallingReferences"}}}}}},"responses":{"200":{"description":"The findings; nothing was created.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"True when no finding is a block."},"findings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["display-name-mismatch","call-reasons-manual","authorizer-free-mail","authorizer-domain-mismatch","reference-phone-duplicate","reference-internal","reference-financial-free-mail","reference-timezone-invalid","logo-unreachable"]},"severity":{"type":"string","enum":["block","warn"]},"field":{"type":"string","description":"The body field the finding is about, e.g. references.financial.email."},"message":{"type":"string"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Business not found"}}}},"/v1/branded-calling/identities/{id}":{"get":{"x-resource-group":"telephony","operationId":"getBrandedCallingIdentity","tags":["Branded Calling"],"summary":"Get a caller identity","description":"Poll this for review and vetting progress, or subscribe to `branded_calling.identity.status_updated`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The identity with its numbers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandedCallingIdentity"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Identity not found"}}},"patch":{"x-resource-group":"telephony","operationId":"updateBrandedCallingIdentity","tags":["Branded Calling"],"summary":"Edit or resubmit a caller identity","description":"Allowed while the identity is `requested`, `changes_requested` or `rejected`.\nAnswering a change request (send `reviewAnswers` keyed by point id, and any\nedited fields) puts it back in review. On a carrier rejection the edits are\napplied at the carrier and the identity is resubmitted straight away.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"type":"string","minLength":1,"maxLength":35,"description":"Shown on the callee's screen. No emoji."},"callReasons":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","maxLength":64},"description":"1 to 10 reasons you call, each up to 64 characters. Pick from GET /v1/branded-calling/call-reasons to skip manual vetting."},"logoUrl":{"type":"string","description":"HTTPS URL of a PNG, JPEG, WebP or SVG logo. Zernio converts it to the 256x256 BMP the carriers require and hosts it."},"authorizer":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string","maxLength":255,"description":"A real person at the business who authorizes the registration."},"email":{"type":"string","format":"email","description":"The carrier emails a 6-digit code here once the identity passes review."}}},"references":{"$ref":"#/components/schemas/BrandedCallingReferences"},"reviewAnswers":{"type":"object","description":"One entry per point id of the open reviewRequest. A text point takes text; a link point takes url; file and link_or_file points take url set to the URL of a file you uploaded first (POST /v1/media/presign). A point id that is not on the open request is a 422.","additionalProperties":{"type":"object","properties":{"text":{"type":"string"},"url":{"type":"string","format":"uri","description":"A live page, or the URL of an uploaded file for file points."}}}},"reviewNote":{"type":"string","maxLength":4000}}}}}},"responses":{"200":{"description":"The updated identity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandedCallingIdentity"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Identity not found"},"409":{"description":"The identity cannot be edited in its current status (code invalid_resource_state)."},"422":{"x-summary":"The reviewAnswers names a point id that is not on the open change request, or no open request exists: fix the ids.","description":"reviewAnswers names a point id that is not on the open change request, or there is no open request (code invalid_field_value, param reviewAnswers)."}}},"delete":{"x-resource-group":"telephony","operationId":"deleteBrandedCallingIdentity","tags":["Branded Calling"],"summary":"Delete a caller identity","description":"Detaches its numbers and removes the identity at the carrier, which ends the monthly fee. Refused while an infringement claim is open.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["deleted"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Identity not found"},"409":{"description":"An infringement claim is open on this identity (code invalid_resource_state)."}}}},"/v1/branded-calling/identities/{id}/verify-email":{"post":{"x-resource-group":"telephony","operationId":"resendBrandedCallingAuthorizerCode","tags":["Branded Calling"],"summary":"Resend the authorizer's code","description":"Emails the authorizer a fresh 6-digit code (the previous one stops working). Only while the identity is `pending_email_verification`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Code sent.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["sent"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Identity not found"},"409":{"description":"The identity is not waiting for a code (code invalid_resource_state)."}}}},"/v1/branded-calling/identities/{id}/verify-email/confirm":{"post":{"x-resource-group":"telephony","operationId":"confirmBrandedCallingAuthorizerEmail","tags":["Branded Calling"],"summary":"Confirm the authorizer's code","description":"The last customer step. On success the stored references are filed and the\nidentity is submitted to carrier vetting in the same call (`in_review`). If a\nlater step fails the identity stays `pending_email_verification` with the email\nalready verified; calling again resumes from that step.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","pattern":"^[0-9]{6}$"}}}}}},"responses":{"200":{"description":"The identity, now in carrier vetting.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandedCallingIdentity"}}}},"400":{"description":"The code is wrong or expired (param code), or the body is invalid."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Identity not found"},"409":{"description":"The identity is not waiting for a code (code invalid_resource_state)."}}}},"/v1/branded-calling/identities/{id}/numbers":{"get":{"x-resource-group":"telephony","operationId":"listBrandedCallingIdentityNumbers","tags":["Branded Calling"],"summary":"List the numbers on a caller identity","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Attached numbers with their vetting status.","content":{"application/json":{"schema":{"type":"object","properties":{"numbers":{"type":"array","items":{"$ref":"#/components/schemas/BrandedCallingIdentityNumber"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Identity not found"}}},"post":{"x-resource-group":"telephony","operationId":"attachBrandedCallingNumbers","tags":["Branded Calling"],"summary":"Attach numbers to a verified identity","description":"Files a Letter of Authorization signed by you (Zernio is named as the authorized agent managing the numbers) and opens a vetting batch of up to 15 US numbers you own.\n\n- The batch is all-or-nothing: one ineligible number refuses the whole call.\n- Each number shows the identity once its own status reaches `verified`.\n- A number belongs to one identity at a time.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phoneNumberIds","signature"],"properties":{"phoneNumberIds":{"type":"array","minItems":1,"maxItems":15,"items":{"type":"string"},"description":"Phone number record ids (from GET /v1/phone-numbers). Active US numbers only."},"signature":{"type":"object","required":["imageBase64"],"properties":{"imageBase64":{"type":"string","description":"The signer's drawn signature as a PNG, base64 (a data:image/png;base64 prefix is accepted)."},"signerName":{"type":"string","maxLength":255,"description":"Printed under the signature. Defaults to the business contact's name."}}}}}}}},"responses":{"201":{"description":"Batch opened.","content":{"application/json":{"schema":{"type":"object","properties":{"numbers":{"type":"array","items":{"$ref":"#/components/schemas/BrandedCallingIdentityNumber"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Identity or phone number not found"},"409":{"description":"The identity is not verified yet, or a number already belongs to an identity (code invalid_resource_state)."},"422":{"description":"A number is not a US number or not active, or the carrier refused the batch (the message names the number)."}}},"delete":{"x-resource-group":"telephony","operationId":"detachBrandedCallingNumbers","tags":["Branded Calling"],"summary":"Detach numbers from an identity","description":"Deregisters the numbers at the carrier and frees them for another identity. Up to 100 per call.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phoneNumbers"],"properties":{"phoneNumbers":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string"},"description":"E.164 numbers currently on this identity."}}}}}},"responses":{"200":{"description":"Numbers detached.","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"array","items":{"type":"string"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Identity not found, or none of the numbers is attached to it"}}}},"/v1/sms/registrations":{"post":{"x-resource-group":"telephony","operationId":"startSmsRegistration","tags":["SMS"],"summary":"Start a carrier registration","description":"Starts the US carrier registration that a number needs before SMS delivers: 10DLC (standard company or sole-proprietor) or toll-free verification.\n\n- 10DLC needs `brand` + `campaign`.\n- Toll-free needs `tollFree`.\n\nApproval is asynchronous; poll `GET /v1/sms/registrations/{id}`. Sole-prop registrations first need the OTP step: a code is texted to the brand's mobile number, submit it via `/verify-otp`.\n\n### Alternatives\n\n- Already have an approved registration? Add another number to it with `POST /v1/phone-numbers/{id}/sms/reuse-registration` instead of registering (and paying the carrier brand fee) again.\n- Rather have your client fill in the legal business details? Create a share link with `POST /v1/sms/registrations/share`.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["registrationType"],"properties":{"registrationType":{"type":"string","enum":["standard_10dlc","sole_prop_10dlc","toll_free"]},"phoneNumbers":{"type":"array","items":{"type":"string"},"description":"Your numbers this registration covers. When omitted or empty on a 10DLC registration, defaults to your active SMS-enabled US local numbers not already covered by another registration."},"brand":{"type":"object","description":"Required for 10DLC. The legal entity behind the traffic (TCR brand).","required":["entityType","displayName","country","vertical","website","street","city","state","postalCode"],"properties":{"entityType":{"type":"string","enum":["PRIVATE_PROFIT","PUBLIC_PROFIT","NON_PROFIT","GOVERNMENT","SOLE_PROPRIETOR"]},"displayName":{"type":"string"},"companyName":{"type":"string","description":"Legal company name. Required for every entityType except SOLE_PROPRIETOR."},"ein":{"type":"string","description":"Required for every entityType except SOLE_PROPRIETOR."},"phone":{"type":"string","description":"Business contact phone. Required for every entityType except SOLE_PROPRIETOR."},"mobilePhone":{"type":"string","description":"Required for SOLE_PROPRIETOR; the verification OTP is texted there (US/CA mobile)."},"street":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country where the company is registered. Companies worldwide can register standard 10DLC (non-US companies use their local tax ID in `ein`; carrier vetting may take longer). SOLE_PROPRIETOR is US/CA only."},"email":{"type":"string","format":"email","description":"Brand contact email; defaults to your account email when omitted."},"website":{"type":"string","description":"The brand's website (sole proprietors may use a social profile such as LinkedIn or a business Facebook page). Carriers verify the brand against it; a bare domain is normalized to https://."},"vertical":{"type":"string","enum":["AGRICULTURE","COMMUNICATION","CONSTRUCTION","EDUCATION","ENERGY","ENTERTAINMENT","FINANCIAL","GAMBLING","GOVERNMENT","HEALTHCARE","HOSPITALITY","HUMAN_RESOURCES","INSURANCE","LEGAL","MANUFACTURING","NGO","POLITICAL","POSTAL","PROFESSIONAL","REAL_ESTATE","RETAIL","TECHNOLOGY","TRANSPORTATION"]},"stockSymbol":{"type":"string"}}},"campaign":{"type":"object","description":"Required for 10DLC. What you'll send and how recipients opt in/out.\n\nThe opt-in/opt-out/help auto-responses (`optinMessage`, `optoutMessage`, `helpMessage`) are optional. When omitted, a compliant, brand-named template with the carrier-required disclosures is generated for you.\n\nIf you send them, they must name the registered brand and carry the disclosures. Submissions that don't are rewritten to the compliant template before the campaign is filed.\n","required":["usecase","description","messageFlow","sample1","sample2","optinKeywords","optoutKeywords","helpKeywords"],"properties":{"usecase":{"type":"string"},"subUsecases":{"type":"array","minItems":2,"maxItems":5,"items":{"type":"string","enum":["2FA","ACCOUNT_NOTIFICATION","CUSTOMER_CARE","DELIVERY_NOTIFICATION","FRAUD_ALERT","HIGHER_EDUCATION","MARKETING","POLLING_VOTING","PUBLIC_SERVICE_ANNOUNCEMENT","SECURITY_ALERT"]},"description":"The concrete kinds of messages a MIXED campaign sends (the carrier\nregistry requires 2-5, and reviewers match them against the sample\nmessages). Omitted: a default pair is applied for MIXED.\n"},"description":{"type":"string","minLength":40,"maxLength":4096},"messageFlow":{"type":"string","minLength":40,"maxLength":2048,"description":"How a recipient ends up receiving your messages (the opt-in flow). Include a link to the page or form where they opt in, because carrier reviewers reject campaigns whose consent they can't verify."},"sample1":{"type":"string","minLength":20},"sample2":{"type":"string","minLength":20,"description":"Second example message; carriers require two distinct samples, so it must differ from sample1."},"helpMessage":{"type":"string","minLength":20,"maxLength":320},"optinKeywords":{"type":"string"},"optinMessage":{"type":"string","minLength":20,"maxLength":320},"optoutKeywords":{"type":"string"},"optoutMessage":{"type":"string","minLength":20,"maxLength":320},"helpKeywords":{"type":"string"},"embeddedLink":{"type":"boolean","description":"Whether messages carry links. Auto-derived from the samples when omitted, so the declaration matches what the reviewer reads."},"embeddedPhone":{"type":"boolean","description":"Whether messages carry phone numbers. Auto-derived from the samples when omitted."},"numberPool":{"type":"boolean"},"ageGated":{"type":"boolean"},"directLending":{"type":"boolean"},"privacyPolicyLink":{"type":"string","description":"Link to your privacy policy. Recommended: reviewers check that it says mobile information is not sold or shared with third parties for promotional purposes. A bare domain is normalized to https://."},"termsAndConditionsLink":{"type":"string","description":"Link to your terms & conditions. A bare domain is normalized to https://."}}},"messagingBrandName":{"type":"string","minLength":2,"maxLength":60,"description":"DBA / trade name used to brand message content (samples and auto-replies) when it differs from the legal name, e.g. a sole proprietor texting under a business name. The legal `brand.displayName` is still what the carrier vets."},"wizardValues":{"type":"object","additionalProperties":{"type":"string"},"description":"Raw dashboard-wizard answers, stored only to prefill edit-and-resubmit. API integrators can omit."},"resubmitRequestId":{"type":"string","description":"Resubmit a registration that was returned for changes. Updates it in place instead of creating a new one."},"tollFree":{"type":"object","description":"Required for toll_free.","required":["businessName","corporateWebsite","phoneNumbers","useCase","useCaseSummary","productionMessageContent","optInWorkflow","optInWorkflowImageUrls","messageVolume","additionalInformation","businessAddr1","businessCity","businessState","businessZip","businessContactFirstName","businessContactLastName","businessContactEmail","businessContactPhone","businessRegistrationNumber","businessRegistrationType","businessRegistrationCountry"],"properties":{"businessName":{"type":"string"},"corporateWebsite":{"type":"string","format":"uri"},"phoneNumbers":{"type":"array","minItems":1,"items":{"type":"string"}},"useCase":{"type":"string"},"useCaseSummary":{"type":"string"},"productionMessageContent":{"type":"string"},"optInWorkflow":{"type":"string","maxLength":500,"description":"How recipients opt in to your messages."},"optInWorkflowImageUrls":{"type":"array","minItems":1,"items":{"type":"string","format":"uri"},"description":"Screenshot URL(s) showing the opt-in flow (at least one)."},"messageVolume":{"type":"string","enum":["10","100","1,000","10,000","100,000","250,000","500,000","750,000","1,000,000","5,000,000","10,000,000+"],"description":"Expected monthly message volume tier."},"additionalInformation":{"type":"string"},"businessAddr1":{"type":"string"},"businessAddr2":{"type":"string"},"businessCity":{"type":"string"},"businessState":{"type":"string"},"businessZip":{"type":"string"},"businessContactFirstName":{"type":"string"},"businessContactLastName":{"type":"string"},"businessContactEmail":{"type":"string","format":"email"},"businessContactPhone":{"type":"string"},"businessRegistrationNumber":{"type":"string"},"businessRegistrationType":{"type":"string","description":"e.g. EIN (US), Companies House (UK), ABN (AU)."},"businessRegistrationCountry":{"type":"string","description":"ISO 3166-1 alpha-2."}}}}}}}},"responses":{"200":{"description":"Registration submitted.","content":{"application/json":{"schema":{"type":"object","properties":{"registrationId":{"type":"string"},"status":{"type":"string","enum":["pending"]},"awaitingOtp":{"type":"boolean","description":"True for sole-prop 10DLC: an OTP was texted to the brand's mobile; submit it via /verify-otp."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/BalanceRequired"},"403":{"description":"The caller is a team member limited to specific profiles; registrations cover the whole account."},"409":{"x-summary":"The brand already exists at the carrier and failed identity verification: reply to fix it, because a new registration would bill again.","description":"The brand already exists at the carrier and failed identity verification (a rejected registration of yours with the same EIN or legal name); the fix is applied to that brand on reply, a new registration would file and bill a second one."},"422":{"description":"Carrier registry rejected a field; `param` names it when known."}}},"get":{"x-resource-group":"telephony","operationId":"listSmsRegistrations","tags":["SMS"],"summary":"List carrier registrations","security":[{"bearerAuth":[]}],"parameters":[{"name":"includeDeactivated","in":"query","required":false,"schema":{"type":"boolean"},"description":"Deactivated (terminated) registrations are hidden by default. Pass true to include them."}],"responses":{"200":{"description":"Registrations, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"registrations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"registrationType":{"type":"string","enum":["standard_10dlc","sole_prop_10dlc","toll_free"]},"displayName":{"type":["string","null"]},"status":{"type":"string","enum":["pending","approved","rejected","requested","changes_requested","deactivated"],"description":"requested/changes_requested = pre-submission review states; customers see them as pending / needs changes."},"brandStatus":{"type":"string","description":"Carrier-registry brand status (e.g. VERIFIED)."},"campaignStatus":{"type":"string"},"brandId":{"type":["string","null"],"description":"TCR brand id, useful when referencing the brand in carrier support threads."},"campaignId":{"type":["string","null"],"description":"TCR campaign id."},"declineReason":{"type":["string","null"]},"tfActionRequiredAt":{"type":["string","null"],"format":"date-time","description":"Toll-free only: when the carrier requested changes (\"Waiting For Customer\"). The request must be resubmitted within 7 days of this timestamp or it expires."},"phoneNumbers":{"type":"array","items":{"type":"string"}},"awaitingOtp":{"type":"boolean","description":"Sole-prop 10DLC only; the OTP step is still pending."},"adminReviewNote":{"type":["string","null"],"description":"The open change request as text (status changes_requested)."},"lastResponseAt":{"type":["string","null"],"format":"date-time","description":"When you last answered a change request."},"previouslyRejected":{"type":"boolean","description":"Rejected by the carriers at least once. A pending registration with this set is our fix, back with the carriers."},"lastRejectedAt":{"type":["string","null"],"format":"date-time","description":"When the carriers last rejected it."},"rejectedBeforeSubmission":{"type":"boolean","description":"Rejected in our review before anything was filed with the carriers (not a carrier rejection; nothing to fix or appeal)."},"otpExpired":{"type":"boolean","description":"Sole proprietor only: the verification code was never entered within 30 days. Start SMS setup again; it revives the same brand with no second brand fee."},"reviewRequest":{"description":"The same change request as points, when the reviewer wrote it that way; null otherwise.","oneOf":[{"$ref":"#/components/schemas/SmsRegistrationReviewRequest"},{"type":"null"}]},"trustScore":{"type":["number","null"],"description":"Carrier-assigned brand trust score; drives throughput."},"throughput":{"type":"object","description":"Carrier throughput tier derived from the trust score.","properties":{"label":{"type":"string"},"smsPerMinute":{"type":"number"},"smsPerDay":{"type":"number"}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The caller is a team member limited to specific profiles; registrations cover the whole account."}}}},"/v1/sms/registrations/preflight":{"post":{"x-resource-group":"telephony","operationId":"preflightSmsRegistration","tags":["SMS"],"summary":"Pre-check a carrier registration","description":"Dry-run of `POST /v1/sms/registrations` for 10DLC. It returns the findings WITHOUT creating anything.\n\nIt does three things:\n\n1. Validates and composes the exact brand/campaign payloads a submission would store (branding, disclosures, auto-replies).\n2. Runs deterministic compliance lints over them.\n3. Runs an AI reviewer over them.\n\nUse it to fix issues before submitting. `block` severity findings indicate a near-certain carrier rejection.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["registrationType","brand","campaign"],"properties":{"registrationType":{"type":"string","enum":["standard_10dlc","sole_prop_10dlc"]},"phoneNumbers":{"type":"array","items":{"type":"string"}},"brand":{"type":"object","description":"Same shape as the registration `brand`."},"campaign":{"type":"object","description":"Same shape as the registration `campaign`."},"messagingBrandName":{"type":"string","minLength":2,"maxLength":60}}}}}},"responses":{"200":{"description":"Composed payloads + findings.","content":{"application/json":{"schema":{"type":"object","properties":{"composed":{"type":"object","description":"The exact payloads a submission would store (post-branding, disclosures appended, auto-replies generated).","properties":{"brand":{"type":"object"},"campaign":{"type":"object"}}},"advisories":{"type":"array","items":{"type":"object","properties":{"field":{"type":["string","null"],"description":"The payload field the finding is about, when attributable."},"code":{"type":["string","null"],"description":"Stable rule id for deterministic findings; absent on AI findings."},"concern":{"type":"string"},"severity":{"type":"string","enum":["block","warn"]}}}},"verdict":{"type":"string","enum":["pass","warn","fail","unreviewed"]},"aiUnavailable":{"type":"boolean","description":"True when the AI portion of the check could not run; advisories then contain only deterministic findings."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/sms/registrations/{id}":{"delete":{"x-resource-group":"telephony","operationId":"deactivateSmsRegistration","tags":["SMS"],"summary":"Deactivate a brand/campaign registration","description":"Terminates the campaign with the carrier registry so the recurring monthly campaign fee stops (carriers bill the first 3 months of a campaign regardless). Idempotent.\n\n- Numbers covered by it can no longer SEND texts (receiving is unaffected) until they're registered under a new brand.\n- Irreversible: a deactivated campaign cannot be restored. Texting again later requires a new registration (new one-time and review fees).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Registration deactivated.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["deactivated"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The caller is a team member limited to specific profiles; registrations cover the whole account."},"404":{"description":"Registration not found"}}},"get":{"x-resource-group":"telephony","operationId":"getSmsRegistration","tags":["SMS"],"summary":"Get a carrier registration","description":"Poll this for approval progress after starting a registration.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Registration","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"registrationType":{"type":"string","enum":["standard_10dlc","sole_prop_10dlc","toll_free"]},"status":{"type":"string","enum":["pending","approved","rejected","requested","changes_requested","deactivated"],"description":"requested/changes_requested = pre-submission review states; customers see them as pending / needs changes."},"brandStatus":{"type":"string"},"campaignStatus":{"type":"string"},"declineReason":{"type":["string","null"]},"phoneNumbers":{"type":"array","items":{"type":"string"}},"awaitingOtp":{"type":"boolean"},"adminReviewNote":{"type":["string","null"],"description":"The open change request as text (status changes_requested)."},"reviewRequest":{"description":"The same change request as points, when the reviewer wrote it that way; null otherwise.","oneOf":[{"$ref":"#/components/schemas/SmsRegistrationReviewRequest"},{"type":"null"}]},"campaignContent":{"type":"object","description":"The submitted campaign content, present only for rejected\nregistrations with a campaign. Edit and resubmit it via the\nappeal endpoint's optional content fields.\n","properties":{"messageFlow":{"type":"string"},"sample1":{"type":"string"},"sample2":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The caller is a team member limited to specific profiles; registrations cover the whole account."},"404":{"description":"Registration not found"}}}},"/v1/sms/registrations/{id}/verify-otp":{"post":{"x-resource-group":"telephony","operationId":"verifySmsRegistrationOtp","tags":["SMS"],"summary":"Submit the sole-prop OTP","description":"Completes sole-proprietor 10DLC brand verification by submitting the\none-time PIN texted to the brand's mobile number. On success the\nregistration continues to campaign creation automatically.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["otpPin"],"properties":{"otpPin":{"type":"string","minLength":4,"maxLength":10}}}}}},"responses":{"200":{"description":"OTP result","content":{"application/json":{"schema":{"type":"object","properties":{"verified":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The caller is a team member limited to specific profiles; registrations cover the whole account."},"404":{"description":"Registration not found"}}}},"/v1/sms/registrations/{id}/resend-otp":{"post":{"x-resource-group":"telephony","operationId":"resendSmsRegistrationOtp","tags":["SMS"],"summary":"Re-send the sole-prop OTP","description":"Re-sends the sole-proprietor verification PIN to the brand's mobile\nnumber. Use it when the original code expired or never arrived. Only\nvalid while the registration is pending and awaiting its OTP; rate\nlimited to one send per minute.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"A new code was sent","content":{"application/json":{"schema":{"type":"object","properties":{"sent":{"type":"boolean"}}}}}},"400":{"description":"Malformed `id`, or the registration is not awaiting a verification code."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The caller is a team member limited to specific profiles; registrations cover the whole account."},"404":{"description":"Registration not found"},"429":{"description":"A code was sent recently. Wait a minute before requesting another"}}}},"/v1/sms/registrations/{id}/appeal":{"post":{"x-resource-group":"telephony","operationId":"appealSmsRegistration","tags":["SMS"],"summary":"Appeal a rejected campaign","description":"Appeals a rejected 10DLC campaign with the carrier registry. On success the registration returns to `pending`.\n\nOnly a registration that reached campaign creation can be appealed. A brand-level rejection should be fixed and re-verified instead.\n\n### Fixing content in the same call\n\nContent rejections (e.g. an opt-in flow without a verifiable form link, or unrealistic samples) should be FIXED in the same call.\n\nPass the corrected `messageFlow` / `sample1` / `sample2` and the campaign is updated before the appeal is filed, so the reviewer sees the new content.\n\nThe current content is on `GET /v1/sms/registrations/{id}` (`campaignContent`).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["appealReason"],"properties":{"appealReason":{"type":"string","minLength":10,"maxLength":2000,"description":"Goes verbatim to the carrier reviewer. Address the decline reason directly."},"messageFlow":{"type":"string","minLength":40,"maxLength":2048,"description":"Corrected opt-in flow; include a link to the opt-in page/form."},"sample1":{"type":"string","minLength":20},"sample2":{"type":"string","minLength":20}}}}}},"responses":{"200":{"description":"Appeal submitted; the registration is pending again.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending"]}}}}}},"400":{"description":"Malformed `id`, or the registration has no campaign to appeal (fix the brand and re-verify instead)."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The caller is a team member limited to specific profiles; registrations cover the whole account."},"404":{"description":"Registration not found"}}}},"/v1/sms/registrations/{id}/respond":{"post":{"x-resource-group":"telephony","operationId":"respondToSmsRegistrationReview","tags":["SMS"],"summary":"Reply to a change request","description":"Replies to a reviewer change request on a registration in `changes_requested` state. Send a note, hosted document URLs (from `POST /v1/sms/opt-in-proof`), or both, sent together.\n\nWhen the request was written as points (`reviewRequest` on the registration), send one entry in `answers` per point.\n\n### What happens next\n\n- The registration returns to `requested` (back in review), and you do not need to resubmit the whole registration.\n- A `rejected` registration can also be answered when we asked for changes to fix it (`reviewRequest` set); it stays `rejected`.\n\nTo change the submitted brand/campaign fields themselves, resubmit via `POST /v1/sms/registrations` with `resubmitRequestId` instead.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":2000,"description":"Answer for the reviewer. Required when no files are sent."},"files":{"type":"array","maxItems":5,"items":{"type":"string"},"description":"Hosted document URLs returned by POST /v1/sms/opt-in-proof."},"requestId":{"type":"string","description":"The `reviewRequest.id` you are answering. When it no longer matches the open request the reply is refused with 409."},"answers":{"type":"array","maxItems":20,"description":"One answer per point of the open `reviewRequest`, each point at most once. Required (every point) when the request has points; a missing, repeated or unknown point is a 400 naming the point ids. At most 10 files per reply.","items":{"type":"object","required":["pointId"],"properties":{"pointId":{"type":"string"},"text":{"type":"string","maxLength":2000,"description":"For `text` points (at least 3 characters)."},"url":{"type":"string","format":"uri","description":"For `link` and `link_or_file` points."},"files":{"type":"array","maxItems":5,"items":{"type":"string"},"description":"Hosted document URLs from POST /v1/sms/opt-in-proof, for `file` and `link_or_file` points."}}}}}}}}},"responses":{"200":{"description":"Reply recorded; the registration is back in review.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["requested","rejected"],"description":"requested = back in our review; rejected = a registration the carriers rejected, where we asked for these answers to fix it (it stays rejected while we do)."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The caller is a team member limited to specific profiles; registrations cover the whole account."},"404":{"description":"Registration not found"},"409":{"description":"The registration is not waiting on changes, or `requestId` is no longer the open request (reload it)."}}}},"/v1/sms/opt-in-proof":{"post":{"x-resource-group":"contacts","operationId":"uploadSmsOptInProofFile","tags":["SMS"],"summary":"Upload opt-in form proof","description":"Hosts a screenshot (or PDF) of your SMS opt-in form and returns its public URL.\n\nInclude that URL in the campaign's `messageFlow` (the opt-in workflow text). The carrier registry has no attachment field, so reviewers verify consent by opening links in that answer.\n\nWorks before a registration exists (use it when registering) and for appeals. `/v1/sms/registrations/{id}/opt-in-proof` is an alias.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"PNG, JPG, WebP, GIF or PDF, max 4MB."}}}}}},"responses":{"200":{"description":"File hosted.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Public URL to reference in the opt-in flow text."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Unsupported file type or file too large"}}}},"/v1/sms/registrations/{id}/opt-in-proof":{"post":{"x-resource-group":"contacts","operationId":"uploadSmsOptInProof","tags":["SMS"],"summary":"Upload opt-in form proof for an appeal","description":"Hosts a screenshot (or PDF) of your SMS opt-in form and returns its public URL.\n\nCarrier reviewers reject campaigns whose consent can't be verified and ask for a \"link/screenshot of the opt-in form\".\n\nThe registry has no attachment field, so include the returned URL inside the `messageFlow` you submit with the appeal (`POST /v1/sms/registrations/{id}/appeal`).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"PNG, JPG, WebP, GIF or PDF, max 4MB."}}}}}},"responses":{"200":{"description":"File hosted.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Public URL to reference in the opt-in flow text."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Registration not found"},"422":{"description":"Unsupported file type or file too large"}}}},"/v1/sms/registrations/share":{"post":{"x-resource-group":"telephony","operationId":"shareSmsRegistration","tags":["SMS"],"summary":"Create a registration share link","description":"Creates a single-use, expiring link (valid 7 days) that lets someone\nelse (whoever has the legal business details) fill in the carrier\nregistration form for one of your numbers, without a Zernio login. The\nregistration is created under your account once the form is submitted.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["numberId"],"properties":{"numberId":{"type":"string","description":"Your phone number's ID (from GET /v1/phone-numbers)."}}}}}},"responses":{"200":{"description":"Share link created.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Number not found"}}}},"/v1/whatsapp/template-library":{"get":{"x-resource-group":"accounts","operationId":"getWhatsAppLibraryTemplate","tags":["WhatsApp Templates"],"summary":"Look up a library template","description":"Look up a single pre-approved Template Library template by its exact name, to introspect its structure before importing it.\n\nMost importantly, it returns the template's `buttons`. A library template with `URL` / `PHONE_NUMBER` buttons must be created with a matching `library_template_button_inputs` array (see Create Template), or Meta rejects it. Use this to discover which inputs to collect.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"},{"name":"name","in":"query","required":true,"schema":{"type":"string"},"description":"Exact library template name"},{"name":"language","in":"query","required":false,"schema":{"type":"string"},"description":"Desired language variant (e.g. es, en_US). If the template is not offered in it, the first available variant is returned and named in the response language field."}],"responses":{"200":{"description":"Library template (or null if no exact match)","content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":["object","null"],"properties":{"name":{"type":"string"},"language":{"type":"string"},"category":{"type":"string"},"body":{"type":"string"},"body_params":{"type":"array","items":{"type":"string"}},"availableLanguages":{"type":"array","items":{"type":"string"}},"buttons":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"QUICK_REPLY, URL, PHONE_NUMBER, OTP, FLOW, ..."},"text":{"type":"string"}}}}}}}}}}},"400":{"description":"Missing or invalid query params"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}}},"/v1/whatsapp/catalogs":{"get":{"x-resource-group":"messages","operationId":"listWhatsAppCatalogs","tags":["WhatsApp"],"summary":"List the catalogs linked to a WhatsApp number","description":"Lists the Meta Commerce catalogs connected to the number's WhatsApp Business Account.\n\nPass `catalogAccountId`. The WhatsApp connection's own (embedded signup) token answers an empty list even when a catalog is linked; only a Meta login with catalog_management sees the link.\n\nA linked catalog is what product, product_list and catalog_message interactive messages sell from (see POST /v1/inbox/conversations/{conversationId}/messages). It is also what customers browse in the WhatsApp app.\n\nCreate and fill catalogs with the /v1/ads/catalogs endpoints.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"},{"$ref":"#/components/parameters/CatalogTokenAccountId"}],"responses":{"200":{"description":"Linked catalogs","content":{"application/json":{"schema":{"type":"object","properties":{"wabaId":{"type":"string"},"catalogs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/AccountUnavailable"}}},"post":{"x-resource-group":"messages","operationId":"linkWhatsAppCatalog","tags":["WhatsApp"],"summary":"Link a catalog to a WhatsApp number","description":"Connects a Meta Commerce catalog (owned by the same business portfolio as the WhatsApp Business Account) to the number's WABA. The WhatsApp connection's own token cannot do this, so pass `catalogAccountId` naming a facebook, instagram or metaads account whose Meta login carries catalog_management.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","catalogId"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"},"catalogAccountId":{"type":"string","description":"Account whose Meta login token performs the call"},"catalogId":{"type":"string","description":"Meta catalog ID"}}}}}},"responses":{"201":{"description":"Linked","content":{"application/json":{"schema":{"type":"object","properties":{"wabaId":{"type":"string"},"catalogs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/AccountUnavailable"}}},"delete":{"x-resource-group":"messages","operationId":"unlinkWhatsAppCatalog","tags":["WhatsApp"],"summary":"Unlink a catalog from a WhatsApp number","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"},{"$ref":"#/components/parameters/CatalogTokenAccountId"},{"name":"catalogId","in":"query","required":true,"schema":{"type":"string"},"description":"Meta catalog ID"}],"responses":{"200":{"description":"Unlinked","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"wabaId":{"type":"string"},"catalogId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/AccountUnavailable"}}}},"/v1/whatsapp/commerce-settings":{"get":{"x-resource-group":"messages","operationId":"getWhatsAppCommerceSettings","tags":["WhatsApp"],"summary":"Get a number's commerce settings","description":"Whether the linked catalog is shown on the business profile (`isCatalogVisible`) and whether customers can build a cart (`isCartEnabled`).","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"},{"$ref":"#/components/parameters/CatalogTokenAccountId"}],"responses":{"200":{"description":"Commerce settings","content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"$ref":"#/components/schemas/WhatsAppCommerceSettings"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/AccountUnavailable"}}},"put":{"x-resource-group":"messages","operationId":"updateWhatsAppCommerceSettings","tags":["WhatsApp"],"summary":"Update a number's commerce settings","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"},"catalogAccountId":{"type":"string"},"isCartEnabled":{"type":"boolean"},"isCatalogVisible":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated settings","content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"$ref":"#/components/schemas/WhatsAppCommerceSettings"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/AccountUnavailable"}}}},"/v1/whatsapp/conversational-automation":{"get":{"x-resource-group":"accounts","operationId":"getWhatsAppConversationalAutomation","tags":["WhatsApp"],"summary":"Get ice breakers and commands","description":"Read the number's conversational automation (Meta's `conversational_automation`): ice breaker prompts, slash commands and the welcome-message flag. A number with none set returns the empty configuration.","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"description":"WhatsApp account ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Current configuration","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WhatsAppConversationalAutomation"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"x-resource-group":"accounts","operationId":"setWhatsAppConversationalAutomation","tags":["WhatsApp"],"summary":"Set ice breakers and commands","description":"Set ice breaker prompts (up to 3, 80 characters each), slash commands (up to 30) and the welcome-message flag on the number. Only the fields you send are changed. A tapped prompt arrives as a normal `message.received` carrying its text.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"}}},{"$ref":"#/components/schemas/WhatsAppConversationalAutomation"}]},"example":{"accountId":"64e1f0a9e2b5af0012ab34cd","enable_welcome_message":true,"prompts":["Track my order","Talk to sales"],"commands":[{"command_name":"help","command_description":"Get help with your order"}]}}}},"responses":{"200":{"description":"Configuration updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"x-resource-group":"accounts","operationId":"deleteWhatsAppConversationalAutomation","tags":["WhatsApp"],"summary":"Clear ice breakers and commands","description":"Remove every prompt and command and turn the welcome message off.","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"description":"WhatsApp account ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Configuration cleared","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/whatsapp/business-profile":{"get":{"x-resource-group":"accounts","operationId":"getWhatsAppBusinessProfile","tags":["WhatsApp"],"summary":"Get business profile","description":"Retrieve the WhatsApp Business profile for the account (about, address, description, email, websites, etc.).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"description":"WhatsApp account ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Business profile retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"businessProfile":{"type":"object","properties":{"about":{"type":"string","description":"Short description (max 139 chars)"},"address":{"type":"string"},"description":{"type":"string","description":"Full description (max 512 chars)"},"email":{"type":"string"},"profilePictureUrl":{"type":"string","format":"uri"},"websites":{"type":"array","items":{"type":"string"},"maxItems":2},"vertical":{"type":"string","description":"Business category"}}}}}}}},"400":{"description":"accountId is required or phone number ID not found"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}},"post":{"x-resource-group":"accounts","operationId":"updateWhatsAppBusinessProfile","tags":["WhatsApp"],"summary":"Update business profile","description":"Update the WhatsApp Business profile. All fields are optional; only provided fields will be updated.\nConstraints: about max 139 chars, description max 512 chars, max 2 websites.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"},"about":{"type":"string","maxLength":139,"description":"Short business description (max 139 characters)"},"address":{"type":"string","description":"Business address"},"description":{"type":"string","maxLength":512,"description":"Full business description (max 512 characters)"},"email":{"type":"string","format":"email","description":"Business email"},"websites":{"type":"array","maxItems":2,"items":{"type":"string","format":"uri"},"description":"Business websites (max 2)"},"vertical":{"type":"string","description":"Business category, one of Meta's keys (e.g. AUTO, ENTERTAIN, RETAIL, PROF_SERVICES, OTHER)"},"profilePictureHandle":{"type":"string","description":"Handle from resumable upload for profile picture"}}},"example":{"accountId":"507f1f77bcf86cd799439011","about":"We help businesses grow","description":"Premium business solutions for startups and enterprises","email":"hello@example.com","websites":["https://example.com"]}}}},"responses":{"200":{"description":"Business profile updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"example":{"success":true,"message":"Business profile updated successfully"}}}},"400":{"description":"Validation error (field too long, too many websites, etc.)"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}}},"/v1/whatsapp/business-profile/photo":{"post":{"x-resource-group":"accounts","operationId":"uploadWhatsAppProfilePhoto","tags":["WhatsApp"],"summary":"Upload profile picture","description":"Upload a new profile picture for the WhatsApp Business Profile.\nUses Meta's resumable upload API under the hood: creates an upload session,\nuploads the image bytes, then updates the business profile with the resulting handle.\n\nProvide the image either as a binary upload (`multipart/form-data` with `file`)\nor as a download URL (`application/json` with `url`). With a URL we fetch the\nimage server-side and upload the bytes for you. Meta's profile-photo API is\nbytes-only, so there is no direct URL passthrough. JPEG/PNG, max 5MB either way.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["accountId","file"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"},"file":{"type":"string","format":"binary","description":"Image file (JPEG or PNG, max 5MB, recommended 640x640)"}}}},"application/json":{"schema":{"type":"object","required":["accountId","url"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"},"url":{"type":"string","format":"uri","description":"Publicly reachable https URL of the image (JPEG or PNG, max 5MB, recommended 640x640). Fetched server-side; must resolve directly without redirects."}}}}}},"responses":{"200":{"description":"Profile picture updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid file type/URL, file too large, or missing parameters"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"},"422":{"description":"Profile photo is locked for WhatsApp coexistence numbers (manage it in the WhatsApp Business app)"}}}},"/v1/whatsapp/business-profile/display-name":{"get":{"x-resource-group":"accounts","operationId":"getWhatsAppDisplayName","tags":["WhatsApp"],"summary":"Get display name status","description":"Fetch the current display name and its Meta review status for a WhatsApp Business account.\nDisplay name changes require Meta approval and can take 1-3 business days.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"description":"WhatsApp account ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Display name info retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"displayName":{"type":"object","properties":{"name":{"type":"string","description":"Current verified display name"},"status":{"type":"string","enum":["APPROVED","PENDING_REVIEW","DECLINED","NONE"],"description":"Meta review status for the display name"},"phoneNumber":{"type":"string","description":"Display phone number"}}}}}}}},"400":{"description":"accountId is required"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found or accountId is not a valid ObjectId"}}},"post":{"x-resource-group":"accounts","operationId":"updateWhatsAppDisplayName","tags":["WhatsApp"],"summary":"Request display name change","description":"Submit a display name change request for the WhatsApp Business account.\nThe new name must follow WhatsApp naming guidelines (3-512 characters, must represent your business).\nChanges require Meta review and approval, which typically takes 1-3 business days.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","displayName"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"},"displayName":{"type":"string","minLength":3,"maxLength":512,"description":"New display name (must follow WhatsApp naming guidelines)"}}},"example":{"accountId":"507f1f77bcf86cd799439011","displayName":"My Business Name"}}}},"responses":{"200":{"description":"Display name change submitted for review","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"displayName":{"type":"object","properties":{"name":{"type":"string"},"status":{"type":"string","enum":["PENDING_REVIEW"]}}}}}}}},"400":{"description":"Invalid display name (too short, too long, or missing)"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}}},"/v1/whatsapp/business-profile/username":{"get":{"x-resource-group":"accounts","operationId":"getWhatsappBusinessUsername","tags":["WhatsApp"],"summary":"Get business username","description":"Fetch the current WhatsApp Business username and its approval status.\nUsername status can be `approved` (active), `reserved` (pending activation), or `none` (no username set).\nIf Meta has not granted username management for the WhatsApp Business Account, the API returns the\nstandard error envelope with code `insufficient_permissions`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"description":"WhatsApp account ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Business username retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"username":{"type":["string","null"],"description":"The current username, or null if none is set"},"status":{"type":"string","enum":["approved","reserved","none"],"description":"Approval state of the username"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Meta has not granted username management for this WhatsApp Business Account (code insufficient_permissions)"},"404":{"description":"WhatsApp account not found"}}},"post":{"x-resource-group":"accounts","operationId":"setWhatsappBusinessUsername","tags":["WhatsApp"],"summary":"Set business username","description":"Claim or transfer a WhatsApp Business username for the account.\n\n### Username rules\n\n- 3-35 characters\n- letters/digits/period/underscore only\n- must contain at least one letter\n- no leading or trailing periods\n- no consecutive periods\n- no `www` prefix\n- no domain TLD suffix (e.g. `.com`)\n\n### Transfers\n\nIf the desired username is currently held by another account, pass `transferAction: \"force_transfer\"` to request a transfer.\n\n### Errors\n\nOn failure the API returns a standard error envelope with one of these codes:\n\n- `whatsapp_username_unavailable`: already taken and transfer not requested\n- `whatsapp_username_ineligible`: account not eligible to claim a username\n- `whatsapp_username_transfer_required`: username is held elsewhere; retry with `force_transfer`\n- `insufficient_permissions`: Meta has not granted username management for this WhatsApp Business Account\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","username"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"},"username":{"type":"string","minLength":3,"maxLength":35,"description":"Desired username. Letters, digits, period, and underscore only. Must contain at least one letter. No leading, trailing, or consecutive periods. No www prefix. No domain TLD suffix.\n"},"transferAction":{"type":"string","enum":["none","force_transfer"],"default":"none","description":"Pass `force_transfer` to request a transfer if the username is held by another account"}}},"example":{"accountId":"507f1f77bcf86cd799439011","username":"mybusiness","transferAction":"none"}}}},"responses":{"200":{"description":"Username claimed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"username":{"type":"string"},"status":{"type":"string","enum":["approved","reserved","none"]}}},"example":{"success":true,"username":"mybusiness","status":"approved"}}}},"400":{"description":"Validation error or username unavailable (see error code in response)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Meta has not granted username management for this WhatsApp Business Account (code insufficient_permissions)"},"404":{"description":"WhatsApp account not found"}}},"delete":{"x-resource-group":"accounts","operationId":"deleteWhatsappBusinessUsername","tags":["WhatsApp"],"summary":"Delete business username","description":"Release the currently claimed WhatsApp Business username from the account.\nAfter deletion the username becomes available for other accounts to claim.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"}}},"example":{"accountId":"507f1f77bcf86cd799439011"}}}},"responses":{"200":{"description":"Username deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Meta has not granted username management for this WhatsApp Business Account (code insufficient_permissions)"},"404":{"description":"WhatsApp account not found"}}}},"/v1/whatsapp/business-profile/username/suggestions":{"get":{"x-resource-group":"accounts","operationId":"getWhatsappBusinessUsernameSuggestions","tags":["WhatsApp"],"summary":"Get username suggestions","description":"Retrieve a list of available WhatsApp Business username suggestions based on the account's\nbusiness profile name. Use these to help users discover valid, unclaimed usernames.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"description":"WhatsApp account ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Username suggestions retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"suggestions":{"type":"array","items":{"type":"string"},"description":"List of available username suggestions"}}},"example":{"success":true,"suggestions":["mybusiness","mybusiness_official","mybiz"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}}},"/v1/whatsapp/number-info":{"get":{"x-resource-group":"contacts","operationId":"getWhatsAppNumberInfo","tags":["WhatsApp Phone Numbers"],"summary":"Get number status","description":"Live snapshot of a connected number straight from Meta.\n\n### Phone-number node\n\n- display number\n- display name + approval\n- quality rating\n- messaging-limit tier\n- throughput\n- official-business badge\n- connection status\n- health_status\n\n### Owning WhatsApp Business Account\n\n- name\n- business verification\n- timezone\n- health_status\n\n### Why live\n\nIt is fetched live because Meta updates quality/tier/name/health over time. The call also refreshes the cached values shown on the connection card.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"}],"responses":{"200":{"description":"Number + WABA status","content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"type":"object","properties":{"display_phone_number":{"type":"string"},"verified_name":{"type":"string"},"name_status":{"type":"string","description":"APPROVED, AVAILABLE_WITHOUT_REVIEW, PENDING_REVIEW, DECLINED, EXPIRED, NONE"},"quality_rating":{"type":"string","description":"GREEN, YELLOW, RED, UNKNOWN"},"messaging_limit_tier":{"type":"string","description":"e.g. TIER_250, TIER_1K, TIER_UNLIMITED"},"throughput":{"type":"object","properties":{"level":{"type":"string","description":"STANDARD or HIGH"}}},"status":{"type":"string","description":"e.g. CONNECTED"},"is_official_business_account":{"type":"boolean"},"platform_type":{"type":"string","description":"e.g. CLOUD_API"},"health_status":{"type":"object","description":"Meta's can_send_message health object (messaging + calling signals)"}}},"waba":{"type":["object","null"],"properties":{"name":{"type":"string"},"business_verification_status":{"type":"string","description":"verified, not_verified, pending, ..."},"timezone_id":{"type":"string","description":"Meta integer timezone-enum id"},"health_status":{"type":"object"}}}}}}}},"400":{"description":"Phone number ID not found on account"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}}},"/v1/whatsapp/pricing-analytics":{"get":{"x-resource-group":"analytics","operationId":"getWhatsAppPricingAnalytics","tags":["WhatsApp Phone Numbers"],"summary":"Get pricing analytics","description":"Message volume and approximate cost for one connected WhatsApp number. Read live from Meta's `pricing_analytics` on the WhatsApp Business Account and scoped to that account's phone number.\n\nMeta's figures are approximate and can lag; Meta bills from its own invoice.\n\nMeta limits how far back and how fine the data goes (for example HALF_HOUR only over short ranges), and answers out-of-range requests with an error.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"},{"name":"start","in":"query","required":true,"schema":{"type":"string","format":"date-time"},"description":"Range start, ISO 8601 date or date-time."},{"name":"end","in":"query","required":true,"schema":{"type":"string","format":"date-time"},"description":"Range end, ISO 8601 date or date-time. Must be after start."},{"name":"granularity","in":"query","required":true,"schema":{"type":"string","enum":["HALF_HOUR","DAILY","MONTHLY"]},"description":"Size of each data point. Use DAILY for short or month-to-date ranges.\n\nMeta refuses MONTHLY when the range is too short for a monthly bucket (for example a range that starts at the beginning of the current month and ends today). That is a 400 with `param: granularity` and Meta's reason in `error`.\n"},{"name":"dimensions","in":"query","required":false,"schema":{"type":"string","example":"PRICING_CATEGORY,COUNTRY"},"description":"Comma-separated breakdowns: COUNTRY, PHONE, PRICING_CATEGORY, PRICING_TYPE, TIER. Without it each data point is a total for the interval."},{"name":"metricTypes","in":"query","required":false,"schema":{"type":"string","example":"COST,VOLUME"},"description":"Comma-separated: COST, VOLUME. Defaults to both."},{"name":"pricingTypes","in":"query","required":false,"schema":{"type":"string","example":"REGULAR"},"description":"Comma-separated filter: REGULAR, FREE_CUSTOMER_SERVICE, FREE_ENTRY_POINT."},{"name":"pricingCategories","in":"query","required":false,"schema":{"type":"string","example":"MARKETING,UTILITY"},"description":"Comma-separated filter of Meta pricing categories, for example MARKETING, MARKETING_LITE, UTILITY, AUTHENTICATION, AUTHENTICATION_INTERNATIONAL, SERVICE, REFERRAL_CONVERSION."},{"name":"countryCodes","in":"query","required":false,"schema":{"type":"string","example":"ES,MX"},"description":"Comma-separated ISO 3166-1 alpha-2 country codes to filter on."}],"responses":{"200":{"description":"Pricing data points for the range","content":{"application/json":{"schema":{"type":"object","required":["accountId","phoneNumber","granularity","start","end","dataPoints"],"properties":{"accountId":{"type":"string"},"phoneNumber":{"type":"string","description":"The number the data is scoped to, digits only."},"granularity":{"type":"string","enum":["HALF_HOUR","DAILY","MONTHLY"]},"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"},"dataPoints":{"type":"array","items":{"type":"object","required":["start","end","phoneNumber","country","tier","pricingType","pricingCategory","volume","cost"],"properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"},"phoneNumber":{"type":["string","null"],"description":"Set when dimensions includes PHONE."},"country":{"type":["string","null"],"description":"Set when dimensions includes COUNTRY."},"tier":{"type":["string","null"],"description":"Volume pricing tier. Set when dimensions includes TIER."},"pricingType":{"type":["string","null"],"description":"Set when dimensions includes PRICING_TYPE."},"pricingCategory":{"type":["string","null"],"description":"Set when dimensions includes PRICING_CATEGORY."},"volume":{"type":["integer","null"],"description":"Messages delivered."},"cost":{"type":["number","null"],"description":"Approximate charge, in the currency of the WABA's payment method."}}}}}},"example":{"accountId":"66e000000000000000000001","phoneNumber":"34600000000","granularity":"DAILY","start":"2026-09-01T00:00:00.000Z","end":"2026-09-30T00:00:00.000Z","dataPoints":[{"start":"2026-09-01T00:00:00.000Z","end":"2026-09-02T00:00:00.000Z","phoneNumber":null,"country":"ES","tier":null,"pricingType":null,"pricingCategory":"MARKETING","volume":12,"cost":0.73}]}}}},"400":{"x-summary":"Meta refused the query and retrying fails the same way: change it, for example widen the date range for monthly granularity.","description":"Invalid query, or Meta refused it. Retrying the same query fails the same way.\n\nWhen Meta refuses:\n\n- `error` carries Meta's own reason (for example \"Too small time window to get monthly granularity data.\" or that COST is not shown for businesses billed through a partner).\n- `code` is `invalid_field_value` and `platformError` holds Meta's raw error.\n- `param` is `granularity` when the range is too short for MONTHLY.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/whatsapp/block-users/status":{"get":{"x-resource-group":"contacts","operationId":"getWhatsAppBlockStatus","tags":["WhatsApp"],"summary":"Check if a user is blocked","description":"Definitive blocked-state lookup for a single contact. Meta exposes no\nmembership endpoint, so this reads Zernio's blocklist mirror (kept in\nsync by the block/unblock endpoints; the first call per account\nbackfills the mirror from Meta's full list). Constant-time regardless\nof blocklist size.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"user","in":"query","required":true,"schema":{"type":"string"},"description":"Consumer wa_id or E.164 phone (leading + optional)"}],"responses":{"200":{"description":"Blocked state","content":{"application/json":{"schema":{"type":"object","properties":{"blocked":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}}},"/v1/whatsapp/block-users":{"get":{"x-resource-group":"contacts","operationId":"getWhatsAppBlockedUsers","tags":["WhatsApp"],"summary":"List blocked users","description":"List the WhatsApp users blocked on this number. Cursor-paginated; pass\n`nextCursor` back as `after` to fetch the next page. The blocklist holds\nup to 64,000 users.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Page size."},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor from a previous response's `nextCursor`."}],"responses":{"200":{"description":"Blocked users","content":{"application/json":{"schema":{"type":"object","properties":{"blockedUsers":{"type":"array","items":{"type":"object","properties":{"waId":{"type":"string","description":"WhatsApp user ID (usually the phone number without `+`)."}}}},"nextCursor":{"type":["string","null"],"description":"Pass as `after` to fetch the next page. Null when there are no more pages."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}},"post":{"x-resource-group":"contacts","operationId":"blockWhatsAppUsers","tags":["WhatsApp"],"summary":"Block users","description":"Block one or more WhatsApp users on this number. Blocked users cannot message your number or see that you are online, and your sends to them return an error.\n\n### Meta constraints\n\nThese are surfaced per-user in `failed`; the request itself still succeeds for the rest of the batch.\n\n- Only users who messaged your business within the last 24 hours can be blocked (failures outside the window report \"Re-engagement required\").\n- Up to 1,000 users per request; the blocklist caps at 64,000.\n- Other WhatsApp Business accounts cannot be blocked.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","users"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"},"users":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"string"},"description":"Phone numbers (E.164, e.g. \"+16505551234\") or WhatsApp user IDs to block."}}}}}},"responses":{"200":{"description":"Per-user results","content":{"application/json":{"schema":{"type":"object","properties":{"blocked":{"type":"array","description":"Users successfully blocked.","items":{"type":"object","properties":{"input":{"type":"string","description":"The value you sent."},"waId":{"type":"string","description":"Resolved WhatsApp user ID."}}}},"failed":{"type":"array","description":"Users that could not be blocked, with reasons.","items":{"type":"object","properties":{"input":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}},"delete":{"x-resource-group":"contacts","operationId":"unblockWhatsAppUsers","tags":["WhatsApp"],"summary":"Unblock users","description":"Unblock one or more previously blocked WhatsApp users on this number.\nUp to 1,000 users per request; per-user failures are reported in\n`failed` without failing the rest of the batch.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","users"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"},"users":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"string"},"description":"Phone numbers (E.164) or WhatsApp user IDs to unblock."}}}}}},"responses":{"200":{"description":"Per-user results","content":{"application/json":{"schema":{"type":"object","properties":{"unblocked":{"type":"array","description":"Users successfully unblocked.","items":{"type":"object","properties":{"input":{"type":"string","description":"The value you sent."},"waId":{"type":"string","description":"Resolved WhatsApp user ID."}}}},"failed":{"type":"array","description":"Users that could not be unblocked, with reasons.","items":{"type":"object","properties":{"input":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}}},"/v1/whatsapp/account-events":{"get":{"x-resource-group":"messages","operationId":"listWhatsAppAccountEvents","tags":["WhatsApp"],"summary":"List account notifications","description":"Returns Meta-originated events recorded for a WhatsApp account, newest first:\n\n- template review outcomes (approved, rejected, paused, category changes)\n- WABA status changes (restricted, disabled, reinstated, disconnected)\n\nEvents are captured from Meta webhooks as they happen. The feed starts at the account's first recorded event and is not backfilled.\n\nComplements the push events `whatsapp.template.status_updated` and `account.disconnected` with a pollable history.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Maximum events to return"}],"responses":{"200":{"description":"Recorded events, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string","description":"WhatsApp account the event belongs to"},"type":{"type":"string","description":"Event kind, e.g. template_approved, template_rejected, account_restricted, account_disconnected"},"severity":{"type":"string","enum":["info","success","warning","critical"]},"title":{"type":"string"},"detail":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}}},"/v1/whatsapp/dataset":{"get":{"x-resource-group":"accounts","operationId":"getWhatsAppDataset","tags":["WhatsApp"],"summary":"Get CTWA conversions dataset","description":"Returns the Meta Click-to-WhatsApp conversions dataset currently linked\nto the WhatsApp account, if one has been provisioned. Reads only from\nthe stored `metadata.metaCapiDatasetId`, never hits Meta, never\ncreates a dataset. Use this to detect whether `POST /v1/whatsapp/conversions`\nis configured for an account.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"}],"responses":{"200":{"description":"Dataset lookup","content":{"application/json":{"schema":{"type":"object","properties":{"datasetId":{"type":["string","null"],"description":"Meta dataset ID linked to the WABA, or null if not provisioned yet"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}},"post":{"x-resource-group":"accounts","operationId":"createWhatsAppDataset","tags":["WhatsApp"],"summary":"Provision CTWA dataset","description":"Creates (or fetches, if one already exists) the Meta dataset that\nClick-to-WhatsApp ad events are reported against via the Conversions\nAPI, and persists its ID on the account as `metadata.metaCapiDatasetId`.\n\nThe call is GET-first idempotent: a WABA can only own one CTWA\ndataset, so a second call after a successful provision is a safe no-op\nthat returns the same ID with `created: false`.\n\nRequires the connected WhatsApp account's token to carry the\n`whatsapp_business_manage_events` permission. If the permission is\nmissing the endpoint returns 422 with a message asking the user to\nreconnect the account.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"}}}}}},"responses":{"200":{"description":"Dataset provisioned (or already present)","content":{"application/json":{"schema":{"type":"object","properties":{"datasetId":{"type":"string","description":"Meta dataset ID linked to the WABA"},"created":{"type":"boolean","description":"True if Meta created a new dataset on this call; false if one already existed"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"},"422":{"description":"Account is missing `whatsapp_business_manage_events`. Reconnect required"},"502":{"description":"Upstream Meta failure during provisioning"}}}},"/v1/phone-numbers":{"get":{"x-resource-group":"telephony","operationId":"listPhoneNumbers","tags":["Phone Numbers"],"summary":"List phone numbers","description":"List all phone numbers purchased by the authenticated user.\nBy default, released numbers are excluded. Connected (bring-your-own)\nWhatsApp numbers are returned in the separate `connected` array; they\nare not billed and have no provisioning lifecycle.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"description":"Filter by status. By default excludes released numbers.\n\n- `status=pending_regulatory` returns the \"provisioning\" view: numbers still in review PLUS recently-declined (last 30 days) ones, so a failed registration surfaces (with `regulatoryDeclineReason`) instead of silently disappearing. Declined numbers can be re-submitted via POST /v1/phone-numbers/{id}/remediate.\n- `verifying` is the short-lived state after the number is provisioned on our side while WhatsApp confirms the activation code. The number is not billed until it reaches `active`.\n","schema":{"type":"string","enum":["provisioning","verifying","pending_payment","pending_regulatory","regulatory_declined","active","suspended","releasing","released"]}},{"name":"profileId","in":"query","required":false,"description":"Filter by profile","schema":{"type":"string"}}],"responses":{"200":{"description":"Phone numbers retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"numbers":{"type":"array","items":{"$ref":"#/components/schemas/OwnedPhoneNumber"}},"connected":{"type":"array","description":"Connected (bring-your-own) WhatsApp numbers: your own WABA\nnumbers linked via Embedded Signup. Not provisioned or billed\nby Zernio, so they are not in `numbers`; `accountId` is the\nsocial-account id used by the messaging and inbox endpoints.\nIncluded only on the default and `status=active` views.\n","items":{"type":"object","properties":{"accountId":{"type":"string"},"phoneNumber":{"type":["string","null"]},"displayName":{"type":["string","null"]},"profileId":{"type":["string","null"]},"connectedAt":{"type":["string","null"],"format":"date-time"},"callingEnabled":{"type":"boolean","description":"Whether WhatsApp Business Calling is enabled on this number."}}}},"imessage":{"type":"array","description":"iMessage phone senders (see /v1/imessage/senders/order). Hosted\nby the iMessage provider, not on your Telnyx numbers: SMS and\nCalls can never be enabled on them, and they bill as iMessage\nsenders. `handle` is null until the carrier assigns the number\nat activation. Included only on the default and `status=active`\nviews.\n","items":{"$ref":"#/components/schemas/ImessageSenderLifecycle"}},"sandbox":{"type":["object","null"],"description":"The shared WhatsApp sandbox (one Zernio-owned number, all users test\nagainst it). Present when the sandbox is configured; null otherwise.\nThe `accountId` lets you address the sandbox in compose endpoints.\n`template` is the only template a sandbox send is allowed to use.\n","properties":{"phoneNumber":{"type":"string","example":"+12029087457"},"accountId":{"type":["string","null"]},"template":{"type":"object","properties":{"name":{"type":"string","example":"sandbox_start"},"language":{"type":"string","example":"en"}}},"isSandbox":{"type":"boolean"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/phone-numbers/{id}":{"get":{"x-resource-group":"telephony","operationId":"getPhoneNumber","tags":["Phone Numbers"],"summary":"Get phone number","description":"Retrieve the current status of a purchased phone number. Poll this to track:\n\n- Meta pre-verification (US sync path)\n- for regulated (Tier 3/4) numbers, the async lifecycle: pending_regulatory → active (or regulatory_declined)\n\nWhen a regulated number has an Onfido ID step, `onfidoVerificationUrl` appears here once the order is placed. Forward it to the end user.\n\nOr subscribe to the whatsapp.number.* webhooks instead of polling.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Phone number record ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Phone number retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumber":{"type":"object","properties":{"id":{"type":"string"},"phoneNumber":{"type":"string"},"status":{"type":"string","enum":["pending_payment","pending_regulatory","regulatory_declined","provisioning","verifying","active","suspended","releasing","released"]},"country":{"type":"string"},"metaPreverifiedId":{"type":"string"},"metaVerificationStatus":{"type":"string"},"onfidoVerificationUrl":{"type":["string","null"],"description":"For a regulated number with an Onfido ID step: the link to forward to the end user. Appears once the order is placed; null otherwise."},"endUserFirstName":{"type":["string","null"]},"endUserLastName":{"type":["string","null"]},"regulatoryDeclineReason":{"type":["string","null"],"description":"Reviewer rejection reason when status is regulatory_declined."},"provisionedAt":{"type":"string","format":"date-time"},"sipTrunkId":{"type":["string","null"],"description":"SIP trunk the number is attached to; null when not trunked. While attached, enabling Calls or WhatsApp calling, requesting WhatsApp verification, and releasing the number all return 409."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is scoped to profiles that do not include this number."},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"x-resource-group":"telephony","operationId":"releasePhoneNumber","tags":["Phone Numbers"],"summary":"Release phone number","description":"Release a purchased phone number. This will:\n1. Disconnect any linked WhatsApp account\n2. Decrement the Stripe subscription quantity (or cancel if last number)\n3. Release the number from Telnyx\n4. Mark the number as released\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Phone number record ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Phone number released successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"phoneNumber":{"type":"object","properties":{"id":{"type":"string"},"phoneNumber":{"type":"string"},"status":{"type":"string","description":"\"released\""},"releasedAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Phone number is already released or being released"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"x-summary":"The number is attached to a SIP trunk or changed state during cancellation: detach it or check its state, then retry.","description":"The number is attached to a SIP trunk (detach it first), or it changed state while a pending order was being cancelled (code invalid_resource_state)."},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/v1/phone-numbers/purchase":{"post":{"x-resource-group":"telephony","operationId":"purchasePhoneNumber","tags":["Phone Numbers"],"summary":"Purchase phone number","description":"Buys a phone number, payment-first. The system provisions a number and auto-assigns it, unless you pass `phoneNumber` to buy one exact number from `GET /v1/phone-numbers/available`.\n\nRequires usage-based billing (the Usage plan). The maximum number of phone numbers is determined by the user's plan.\n\n### Outcomes\n\n- Usage-based billing active and a payment method on file: the number provisions inline and bills per month on your usage-based invoice (there is no checkout redirect).\n- No payment method on file: `402 PAYMENT_REQUIRED`.\n- A regulated country: `202` with `status: \"kyc_required\"` and a `kycUrl`.\n\n### Price\n\nThe monthly price is the one `GET /v1/phone-numbers/countries` quotes for that country and `numberType` at the time of purchase, and it is stamped on the number. Later rate-card changes never move a number you already own.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId"],"properties":{"profileId":{"type":"string","description":"Profile for the number, which may already hold other numbers. Without it the number goes to the default profile. The response's `profileId` carries the assignment.\n"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country for the number (default US). International numbers require usage-based billing. Tier 3/4 countries return 202 { status: \"kyc_required\", kycUrl }. The customer must complete KYC at that URL before the number is ordered. See GET /v1/phone-numbers/countries.\n","default":"US"},"numberType":{"type":"string","enum":["local","mobile","national","toll_free"],"description":"Which of the country's offered number types to order (see `types[]` on GET /v1/phone-numbers/countries). Omitted = the country's default type, always the WhatsApp-safe choice.\n\nCapabilities, price and KYC requirements are per (country, type):\n\n- toll_free can never connect WhatsApp (400 when combined with connectWhatsapp:true).\n- wantsSms:true requires an SMS-capable type.\n"},"areaCode":{"type":"string","pattern":"^\\d{1,4}$","description":"Area code (national destination code, e.g. 11 for Sao Paulo) the number must be in. Omit for any area. Get live options from GET /v1/phone-numbers/availability (areaOptions).\n\nHard constraint: when the area has no deliverable inventory, the purchase fails with 409 code AREA_CODE_UNAVAILABLE instead of assigning a number from another area. Later replacements stay in this area too.\n"},"claimId":{"type":"string","description":"Keyless calls only: a `claimId` from a keyless GET /v1/phone-numbers/available. The 401 then carries a `claimUrl` for that exact number. Ignored when an API key is sent.\n"},"phoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"One exact number to buy, in E.164, taken from GET /v1/phone-numbers/available.\n\nHard constraint: when it is no longer available (bought by someone else, or WhatsApp's buy-time check rejects it), the purchase fails with 409 code PHONE_NUMBER_UNAVAILABLE instead of assigning another number. Search again and pick another.\n\nOnly for countries and types that activate instantly: a regulated one (202 kyc_required) returns 400 when phoneNumber is set.\n"},"connectWhatsapp":{"type":"boolean","default":true,"description":"A phone number is the unit; WhatsApp is one optional feature. Omitted defaults to the WhatsApp provisioning path.\n\nPass false to buy a STANDALONE number (Calls/SMS only): provisioning skips the Meta pre-verify/OTP steps and the number activates immediately. WhatsApp can be connected to a standalone number later from the connect flow.\n"},"wantsSms":{"type":"boolean","default":false,"description":"SMS capability is per-number, not per-country. Pass true to provision from the SMS-capable inventory pool so the number can actually text (see also GET /v1/phone-numbers/available with sms=true, and smsAvailable on GET /v1/phone-numbers/countries).\n"},"wantsWhatsapp":{"type":"boolean","default":false,"description":"Declare WhatsApp intent on a STANDALONE purchase (connectWhatsapp:false). The number still activates and bills immediately.\n\nIf WhatsApp's buy-time check rejects the assigned number, it is automatically swapped for a WhatsApp-eligible one during the purchase, instead of being delivered with WhatsApp unavailable.\n\nIgnored on the WhatsApp provisioning path (connectWhatsapp omitted or true), which always delivers a WhatsApp-verified number.\n"},"purchaseIntentId":{"type":"string","maxLength":100,"description":"Optional idempotency key. Send the same value when retrying a purchase: if a number was already bought under this key, the API returns { status: \"already_purchased\", numberId, phoneNumber, profileId } instead of provisioning a second number. Generate a fresh key for each genuinely new purchase.\n"},"allowMultiple":{"type":"boolean","default":false,"description":"Any second purchase within 10 minutes of a previous one is rejected with 409 code PURCHASE_VELOCITY as duplicate protection. Pass true to confirm the additional purchase is intentional (e.g. bulk provisioning).\n"}}},"example":{"profileId":"507f1f77bcf86cd799439011","country":"DE"}}}},"responses":{"200":{"description":"Either a checkout URL (first number) or the provisioned phone number (subsequent numbers).\n","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Checkout session created (first number)","properties":{"message":{"type":"string"},"checkoutUrl":{"type":"string","format":"uri"}}},{"type":"object","description":"Phone number provisioned inline (subsequent numbers)","properties":{"message":{"type":"string"},"phoneNumber":{"type":"object","properties":{"id":{"type":"string"},"phoneNumber":{"type":"string"},"status":{"type":"string"},"country":{"type":"string"},"provisionedAt":{"type":"string","format":"date-time"},"metaPreverifiedId":{"type":"string"},"metaVerificationStatus":{"type":"string"},"profileId":{"type":"string","description":"The profile the number was actually assigned to."}}}}},{"type":"object","description":"A number was already purchased under the supplied purchaseIntentId; no new number was provisioned.\n","properties":{"status":{"type":"string","enum":["already_purchased"]},"numberId":{"type":"string"},"phoneNumber":{"type":"string"},"profileId":{"type":"string","description":"The profile the number was actually assigned to."}}}]}}}},"202":{"description":"Country requires end-user KYC before the number can be ordered.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["kyc_required"]},"country":{"type":"string"},"numberType":{"type":"string","description":"The type that will be ordered after KYC approval."},"kycUrl":{"type":"string"}}}}}},"400":{"description":"Plan limit reached, profileId required, or country not available"},"401":{"x-summary":"The API key is missing or invalid: send a valid key, or hand the keyless purchase claim link to the number's owner.","description":"Missing or invalid API key.\n\nA call with no key at all gets the purchase back as a claim. `details.claimUrl` is a signup link opening the dashboard's confirm step for the requested `country`, `numberType` and `areaCode` (or for the number behind `claimId`, from a keyless GET /v1/phone-numbers/available).\n\nHand it to the person who will own the number.\n","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"object","properties":{"claimId":{"type":"string"},"claimUrl":{"type":"string"}}}}}}}},"402":{"x-summary":"A payment method is required because the usage-based account has no card on file: add a card, then retry.","description":"Payment method required (usage-based billing account with no card on file): code PAYMENT_REQUIRED, add a card, then retry. On balance billing with the balance at $0: code insufficient_balance or usage_limit_reached, top up in Billing, then retry."},"403":{"description":"A paid plan is required"},"409":{"x-summary":"The purchase did not happen: retry with `allowMultiple` after a recent purchase, or pick another area, number or country.","description":"The purchase was not made. The code says why:\n\n- PURCHASE_VELOCITY: duplicate-purchase protection, another number was purchased within the last 10 minutes. Retry with allowMultiple: true to confirm.\n- AREA_CODE_UNAVAILABLE: the requested areaCode has no deliverable inventory right now. Pick another area or omit areaCode.\n- PHONE_NUMBER_UNAVAILABLE: search again and pick another number.\n- COUNTRY_OUT_OF_STOCK: this country and type have no orderable numbers right now; pick another.\n- NO_WHATSAPP_ELIGIBLE_NUMBER: every number the carrier offered is one WhatsApp refuses. Pass an areaCode or try again for a fresh batch.\n","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["PURCHASE_VELOCITY","AREA_CODE_UNAVAILABLE","PHONE_NUMBER_UNAVAILABLE","COUNTRY_OUT_OF_STOCK","NO_WHATSAPP_ELIGIBLE_NUMBER"]}}}}}},"422":{"x-summary":"International numbers require usage-based billing, and legacy Stripe users are limited to the US: switch to usage-based billing.","description":"International numbers require usage-based billing (legacy Stripe users are US-only). Response body code: USAGE_BILLING_REQUIRED."},"503":{"description":"The carrier could not take the order just now (code CARRIER_UNAVAILABLE); the number is not taken, retry the same request in a minute.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["CARRIER_UNAVAILABLE"]}}}}}}}}},"/v1/phone-numbers/claims/{claimId}":{"get":{"x-resource-group":"telephony","operationId":"getPhoneNumberClaim","tags":["Phone Numbers"],"summary":"Resolve a number claim","description":"Resolves a `claimId` from a keyless search or purchase into the\nselection it carries (country, number type, area and exact number)\npriced at today's rate. The dashboard calls it when a person lands\nfrom a `claimUrl`. The number is not held, so buying it can still fail\nwith 409 PHONE_NUMBER_UNAVAILABLE.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"claimId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The claimed selection.","content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"object","properties":{"code":{"type":"string"},"needsKyc":{"type":"boolean"},"monthlyCents":{"type":"integer"},"types":{"type":"array","items":{"type":"object"}}}},"type":{"type":"object","description":"The claimed number type, in the shape of `types[]` on GET /v1/phone-numbers/countries."},"area":{"type":["object","null"],"properties":{"ndc":{"type":"string"},"name":{"type":"string"},"count":{"type":"integer"}}},"phoneNumber":{"type":["string","null"],"description":"E.164, or null for an any-number claim."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"The claim expired (after 7 days), is invalid, or its country or type is no longer sold."}}}},"/v1/phone-numbers/countries":{"get":{"x-resource-group":"telephony","operationId":"listPhoneNumberCountries","tags":["Phone Numbers"],"summary":"List offerable number countries","description":"The phone number countries available to purchase. Drives the country picker.\n\n### Per country\n\n- flat monthly price (cents)\n- regulatory tier\n- whether it needs end-user KYC (Tier 3/4)\n- per-feature availability: PSTN calls, WhatsApp, SMS, and WhatsApp Business Calling outbound\n\nTier-4 countries appear only when enabled.\n\nNo API key needed: the catalog is public so you can browse it before you have an account.\n","security":[],"responses":{"200":{"description":"Offerable countries, cheapest first.","content":{"application/json":{"schema":{"type":"object","properties":{"countries":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"ISO 3166-1 alpha-2"},"tier":{"type":"integer","enum":[1,2,3,4]},"monthlyCents":{"type":"integer","description":"Price a NEW number in this country costs per month, in cents, for the default (first) type. 1.5x the carrier's monthly cost, rounded up to a whole dollar, minimum $3."},"needsKyc":{"type":"boolean"},"callsAvailable":{"type":"boolean","description":"Regular phone (PSTN) calling on the number, inbound + outbound. Available on every offerable country."},"whatsappAvailable":{"type":"boolean","description":"WhatsApp can be enabled on at least one number type from this country; types[].whatsappAvailable says which."},"smsAvailable":{"type":"boolean","description":"Whether this country's number type can do SMS. Use it to filter the picker when the buyer wants SMS (pair with `wantsSms` on purchase)."},"outboundCallingAvailable":{"type":"boolean","description":"WhatsApp Business Calling (BIC) outbound availability, a Meta feature blocked in some countries. NOT the PSTN Calls feature (`callsAvailable`)."},"inStock":{"type":"boolean","description":"Live carrier-stock snapshot (refreshed every 6h + on availability checks): false when NO offered type currently has deliverable inventory, so a purchase would fail. Treat as advisory; the purchase itself re-checks."},"preOrderable":{"type":"boolean","description":"At least one out-of-stock type here can be pre-ordered (see `types[].preOrderable`)."},"types":{"type":"array","description":"Every number type offered in this country (default first). Capabilities, KYC tier, monthly price, and stock are per type. The country-level fields above mirror the first (default) entry. Pass the chosen `numberType` to POST /v1/phone-numbers/purchase.\n","items":{"type":"object","properties":{"numberType":{"type":"string","enum":["local","mobile","national","toll_free"]},"tier":{"type":["integer","null"],"enum":[1,2,3,4,null],"description":"Null on a `fulfilment: request` type, whose document tier is only known once its requirements are read."},"needsKyc":{"type":"boolean"},"monthlyCents":{"type":"integer","description":"Price a NEW number of this type costs per month, in cents."},"whatsappAvailable":{"type":"boolean","description":"False for toll_free (WhatsApp does not reliably register toll-free numbers) and for pairs Meta refuses, such as Chilean local (+56 2)."},"smsAvailable":{"type":"boolean"},"callsAvailable":{"type":"boolean"},"inStock":{"type":"boolean"},"fulfilment":{"type":"string","enum":["instant","request"],"description":"`request`: the carrier stocks this type nowhere and only sources it to order, so it is always a pre-order."},"preOrderable":{"type":"boolean","description":"Out of stock but orderable anyway. Submit KYC as usual (POST /v1/phone-numbers/kyc): we buy regular stock the moment it returns, otherwise the carrier sources the number. Usually 2 to 4 weeks, never guaranteed. Only document tiers (3/4) qualify, and nothing is billed until the number is active."}}}}}}}}}}}}}}},"/v1/phone-numbers/available":{"get":{"x-resource-group":"telephony","operationId":"searchAvailablePhoneNumbers","tags":["Phone Numbers"],"summary":"Search available numbers","description":"Search the provider's inventory for numbers available to purchase in a country (default US). Optional filters narrow the results.\n\n- The country must be offerable (see GET /v1/phone-numbers/countries).\n- Voice capability is always required. Pass `sms=true` to only see numbers that can also text (SMS support is per-number, not per-country).\n- Numbers a purchase would refuse are left out.\n- Any result's `phoneNumber` can be bought exactly by passing it to POST /v1/phone-numbers/purchase.\n\n### Without an API key\n\nThe endpoint works without an API key. Keyless calls get up to 12 results with the middle digits masked (`maskedNumber`), each with a `claimId` and a `claimUrl`.\n\nThe `claimUrl` is a signup link that lands a person on the dashboard's confirm step with that number picked, so an agent can search for a user and hand them one link.\n\nKeyless calls are rate limited per IP and results are cached for a few minutes. With an API key you get full numbers and no claim fields.\n","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"US"},"description":"ISO code, or `auto` on the keyless shape to search the caller's own country (from their IP) near their city, falling back to US."},{"name":"numberType","in":"query","required":false,"description":"Number type; defaults to the country's WhatsApp-safe type (the same name as on purchase, availability and kyc)","schema":{"type":"string","enum":["local","mobile","national","toll_free"]}},{"name":"areaCode","in":"query","required":false,"description":"Area code or national dialing code the number must start with, e.g. 415 or 91","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"deprecated":true,"description":"Alias of numberType, kept for existing callers","schema":{"type":"string"}},{"name":"prefix","in":"query","required":false,"deprecated":true,"description":"Alias of areaCode, kept for existing callers","schema":{"type":"string"}},{"name":"locality","in":"query","required":false,"description":"A city name, matched against the numbering plan (accents and common aliases allowed) and searched by that city's area codes; a name no city of the plan matches returns no numbers. `areaCode` takes a city name too.","schema":{"type":"string"}},{"name":"contains","in":"query","required":false,"description":"Pattern to match within the number","schema":{"type":"string"}},{"name":"sms","in":"query","required":false,"schema":{"type":"boolean"},"description":"true narrows the pool to SMS-capable numbers. Each result still carries its full `features` list for per-number capability badging."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"maximum":100}},{"name":"masked","in":"query","required":false,"schema":{"type":"boolean"},"description":"true returns the keyless shape (masked numbers with claimId and claimUrl) even when you send an API key, e.g. to hand a user a signup link for a number."}],"responses":{"200":{"description":"Available numbers.","content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string"},"numberType":{"type":"string"},"requireSms":{"type":"boolean","description":"Echo of the `sms` filter applied to this search."},"numbers":{"type":"array","items":{"type":"object","properties":{"phoneNumber":{"type":"string","description":"E.164. Pass it as `phoneNumber` on POST /v1/phone-numbers/purchase to buy this exact number."},"features":{"type":"array","items":{"type":"string"},"description":"Provider capability list for this number (e.g. voice, sms, mms)."},"locality":{"type":"string","description":"Town or rate center the number belongs to, as the carrier names it (e.g. WACO)."},"bestEffort":{"type":"boolean","description":"true when the carrier added this number because too few matched your filters, so it may be outside the requested prefix or locality."},"maskedNumber":{"type":"string","description":"Keyless calls only, in place of `phoneNumber`: the number with its middle digits masked, e.g. +44 20 •••• 0123."},"numberType":{"type":"string","description":"Keyless calls only. Without a `numberType` filter a keyless search mixes every type the country sells, so each result names its own."},"claimId":{"type":"string","description":"Keyless calls only. Opaque, expires after 7 days. Pass it as `claimId` on a keyless POST /v1/phone-numbers/purchase."},"claimUrl":{"type":"string","description":"Keyless calls only. Signup link that opens the dashboard's confirm step for this number. The number is not held: if it is gone by then, the buyer picks another in the same area."}}}},"masked":{"type":"boolean","description":"true on keyless calls."},"near":{"type":["string","null"],"description":"With `country=auto`: the caller's city the results were narrowed to, or null when there was no stock there."},"claimId":{"type":"string","description":"Keyless calls only: a claim for any number matching this search's country, type and area."},"claimUrl":{"type":"string","description":"Keyless calls only: signup link for any number matching this search."}}}}}},"400":{"x-summary":"The country is not offerable, the numberType is not offered, or the request has an unknown query parameter: fix the request.","description":"Country not offerable, numberType outside the four offered, or a query parameter this endpoint does not know (the message lists the accepted ones; nothing is silently ignored)."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"x-summary":"The keyless rate limit was reached: retry later or send an API key.","description":"Keyless rate limit reached. Retry later or send an API key."}}}},"/v1/phone-numbers/availability":{"get":{"x-resource-group":"telephony","operationId":"checkPhoneNumberAvailability","tags":["Phone Numbers"],"summary":"Check country availability","description":"Pre-purchase check, so you can warn BEFORE a customer invests in KYC (regulated review is async, 1-3 days). Call this before starting the KYC form for regulated countries.\n\nIt tells you whether we have deliverable inventory, and what address the customer needs:\n\n- `addressConstraint: geo`: the registered address MUST be in one of the returned `areas` (the only place we have stock). A different-area address passes pre-approval but the number can never be assigned.\n- `addressConstraint: country`: any in-country address works.\n- `addressConstraint: none`: field-only / instant country, no address.\n\n### Without an API key\n\nIt answers from cache only and returns just `country`, `numberType` and `areaOptions`, for building an area picker before signup.\n","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"country","in":"query","required":true,"schema":{"type":"string"},"description":"ISO-2 country code."},{"name":"numberType","in":"query","required":false,"schema":{"type":"string","enum":["local","mobile","national","toll_free"]},"description":"Check a specific offered type (stock and address constraints are per type). Omitted = the country's default type."},{"name":"sms","in":"query","required":false,"schema":{"type":"boolean"},"description":"Pass true when the buyer wants SMS: availability, areas, and areaOptions then describe the SMS-capable pool (an SMS purchase orders from it), not the wider voice-only pool."}],"responses":{"200":{"description":"Availability + address constraint.","content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string"},"numberType":{"type":"string"},"available":{"type":"boolean","description":"Whether deliverable voice inventory exists right now."},"preOrderable":{"type":"boolean","description":"Nothing deliverable now, but this pair can be pre-ordered: submit KYC as usual and we buy regular stock the moment it returns, otherwise the carrier sources the number (usually 2 to 4 weeks, never guaranteed). Only document tiers (3/4) qualify."},"addressConstraint":{"type":"string","enum":["geo","country","none"]},"areas":{"type":"array","description":"For `geo` only: the area(s) the registered address must be in.","items":{"type":"string"}},"areaOptions":{"type":"array","description":"Live inventory grouped by area code. Empty when out of stock (or the area lookup failed). Equal to `areaAvailability.inStock`.\n\n- US and CA: the full country inventory (every area code with stock), recognizable metros first, then alphabetical.\n- Other countries: largest stock first, listing the areas in the latest inventory page (up to 500 numbers, which for most countries is the entire pool).\n\nPass a chosen `ndc` as `areaCode` on POST /v1/phone-numbers/purchase (or on the KYC submit for regulated countries) to require that area.\n","items":{"type":"object","properties":{"ndc":{"type":"string","description":"Area code (national destination code), e.g. \"11\"."},"name":{"type":"string","description":"Area name: \"City, ST\" for US/CA (e.g. \"Miami, FL\"), city otherwise (e.g. \"Sao Paulo\")."},"count":{"type":"integer","description":"Numbers available in this area: country-wide count for US/CA, numbers seen on the latest inventory page otherwise."}}}},"soldOutAreas":{"type":"array","description":"Every area of the country's numbering plan with nothing deliverable now: `areaAvailability.preOrder` plus `areaAvailability.outOfStock`, kept for older clients. Pass one as `areaCode` with `preOrder: true` on the KYC submit when `preOrderable` is true, or watch it with POST /v1/phone-numbers/stock-watches.\n","items":{"type":"object","properties":{"ndc":{"type":"string","description":"Area code (national destination code)."},"name":{"type":"string","description":"Area name."},"preOrderable":{"type":"boolean","description":"Whether this area can be pre-ordered: the carrier sources a number in it (usually 2 to 4 weeks, never guaranteed)."}}}},"areaAvailability":{"type":"object","description":"Every area of the country's numbering plan (Google libphonenumber geocoding, one row per city: Madrid covers 910 to 919), each in one of three states.\n\nRefreshed every 6 hours from the carrier's own inventory counts. The same answer the dashboard picker and the public country pages show.\n\nEmpty lists mean the pair has no cached coverage yet, not that the country has no areas.\n","properties":{"inStock":{"type":"array","description":"Deliverable numbers now, deepest first. Pass `ndc` as `areaCode` to hold the order to it.","items":{"type":"object","properties":{"ndc":{"type":"string"},"name":{"type":"string"},"count":{"type":"integer","description":"Numbers we can sell there: the carrier count minus the numbers we hold back (WhatsApp refused them or another order holds them)."},"ndcs":{"type":"array","items":{"type":"string"},"description":"Every area code of the city, deepest first (Madrid: 915, 911, 910, ...). `ndc` is the one an order is placed against."},"aliases":{"type":"array","items":{"type":"string"},"description":"Other names the area answers to, present only when it has some (Milano for Milan, Sevilla for Seville)."}}}},"preOrder":{"type":"array","description":"The carrier lists nothing there and the number type is a document tier: submit KYC with `areaCode` and `preOrder: true`, the carrier sources one (usually 2 to 4 weeks, never guaranteed), nothing is billed until it is active.","items":{"type":"object","properties":{"ndc":{"type":"string"},"name":{"type":"string"},"ndcs":{"type":"array","items":{"type":"string"},"description":"Every area code of the city, deepest first (Madrid: 915, 911, 910, ...). `ndc` is the one an order is placed against."},"aliases":{"type":"array","items":{"type":"string"},"description":"Other names the area answers to, present only when it has some (Milano for Milan, Sevilla for Seville)."}}}},"outOfStock":{"type":"array","description":"Nothing deliverable and no pre-order: `listed` > 0 is stock the carrier shows that WhatsApp refused recently (held back until it clears), 0 is a dry area of an instant tier. A stock watch (POST /v1/phone-numbers/stock-watches with `areaCode`) is the way to hear when it is back.","items":{"type":"object","properties":{"ndc":{"type":"string"},"name":{"type":"string"},"listed":{"type":"integer"},"ndcs":{"type":"array","items":{"type":"string"},"description":"Every area code of the city, deepest first (Madrid: 915, 911, 910, ...). `ndc` is the one an order is placed against."},"aliases":{"type":"array","items":{"type":"string"},"description":"Other names the area answers to, present only when it has some (Milano for Milan, Sevilla for Seville)."}}}}}}}}}}},"400":{"description":"Country not offerable, or the inventory provider rejected the lookup (its 4xx status is forwarded as-is)."},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"description":"The inventory provider was unreachable or returned an unclassified error."}}}},"/v1/whatsapp/phone-numbers":{"get":{"x-resource-group":"telephony","operationId":"getWhatsAppPhoneNumbers","deprecated":true,"tags":["WhatsApp Phone Numbers"],"summary":"List phone numbers","description":"Deprecated alias of `/v1/phone-numbers`; same contract. New\nintegrations should use that path.\n\nList all WhatsApp phone numbers purchased by the authenticated user.\nBy default, released numbers are excluded. Connected (bring-your-own)\nnumbers are returned in the separate `connected` array. They are not\nbilled and have no provisioning lifecycle.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"description":"Filter by status. By default, released numbers are excluded.\n\n- `status=pending_regulatory` returns the \"provisioning\" view: numbers still in review PLUS ones declined in the last 30 days, so a failed registration surfaces (with `regulatoryDeclineReason`) instead of disappearing. Re-submit declined numbers via POST /v1/whatsapp/phone-numbers/{id}/remediate.\n- `verifying`: the short-lived state after the number is provisioned on our side while WhatsApp confirms the activation code. Not billed until it reaches `active`.\n","schema":{"type":"string","enum":["provisioning","verifying","pending_payment","pending_regulatory","regulatory_declined","active","suspended","releasing","released"]}},{"name":"profileId","in":"query","required":false,"description":"Filter by profile","schema":{"type":"string"}}],"responses":{"200":{"description":"Phone numbers retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"numbers":{"type":"array","items":{"$ref":"#/components/schemas/OwnedPhoneNumber"}},"connected":{"type":"array","description":"Connected (bring-your-own) WhatsApp numbers: your own WABA\nnumbers linked via Embedded Signup. Not provisioned or billed\nby Zernio, so they are not in `numbers`; `accountId` is the\nsocial-account id used by the messaging and inbox endpoints.\nIncluded only on the default and `status=active` views.\n","items":{"type":"object","properties":{"accountId":{"type":"string"},"phoneNumber":{"type":["string","null"]},"displayName":{"type":["string","null"]},"profileId":{"type":["string","null"]},"connectedAt":{"type":["string","null"],"format":"date-time"},"callingEnabled":{"type":"boolean","description":"Whether WhatsApp Business Calling is enabled on this number."}}}},"imessage":{"type":"array","description":"iMessage phone senders (see /v1/imessage/senders/order). Hosted\nby the iMessage provider, not on your Telnyx numbers: SMS and\nCalls can never be enabled on them, and they bill as iMessage\nsenders. `handle` is null until the carrier assigns the number\nat activation. Included only on the default and `status=active`\nviews.\n","items":{"$ref":"#/components/schemas/ImessageSenderLifecycle"}},"sandbox":{"type":["object","null"],"description":"The shared WhatsApp sandbox (one Zernio-owned number, all users test\nagainst it). Present when the sandbox is configured; null otherwise.\nThe `accountId` lets you address the sandbox in compose endpoints.\n`template` is the only template a sandbox send is allowed to use.\n","properties":{"phoneNumber":{"type":"string","example":"+12029087457"},"accountId":{"type":["string","null"]},"template":{"type":"object","properties":{"name":{"type":"string","example":"sandbox_start"},"language":{"type":"string","example":"en"}}},"isSandbox":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/whatsapp/phone-numbers/purchase":{"post":{"x-resource-group":"telephony","operationId":"purchaseWhatsAppPhoneNumber","deprecated":true,"tags":["WhatsApp Phone Numbers"],"summary":"Purchase phone number","description":"Deprecated alias of `/v1/phone-numbers/purchase`; same contract. New integrations should use that path.\n\nRequires usage-based billing (the Usage plan). The maximum number of phone numbers is determined by the user's plan.\n\n### Payment-first purchase\n\nThe system provisions a number and auto-assigns it, unless you pass `phoneNumber` to buy one exact number from `GET /v1/phone-numbers/available`.\n\nWith usage-based billing active and a payment method on file, the number provisions inline and bills per month on your usage-based invoice (there is no checkout redirect).\n\n- No payment method on file returns `402 PAYMENT_REQUIRED`.\n- A regulated country returns `202` with `status: \"kyc_required\"` and a `kycUrl`.\n\n### Price\n\nThe monthly price is the one `GET /v1/phone-numbers/countries` quotes for that country and `numberType` at the time of purchase. It is stamped on the number: later rate-card changes never move a number you already own.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId"],"properties":{"profileId":{"type":"string","description":"Profile to associate the number with"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country for the number (default US). International numbers require usage-based billing. Tier 3/4 countries return 202 { status: \"kyc_required\", kycUrl }. The customer must complete KYC at that URL before the number is ordered. See GET /v1/whatsapp/phone-numbers/countries.\n","default":"US"},"phoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"One exact number to buy, in E.164, taken from GET /v1/phone-numbers/available. Fails with 409 code PHONE_NUMBER_UNAVAILABLE when it is no longer available.\n"},"purchaseIntentId":{"type":"string","maxLength":100,"description":"Optional idempotency key. Send the same value when retrying a purchase: if a number was already bought under this key, the API returns { status: \"already_purchased\", numberId, phoneNumber } instead of provisioning a second number. Generate a fresh key for each genuinely new purchase.\n"},"allowMultiple":{"type":"boolean","default":false,"description":"Any second purchase within 10 minutes of a previous one is rejected with 409 code PURCHASE_VELOCITY as duplicate protection. Pass true to confirm the additional purchase is intentional (e.g. bulk provisioning).\n"}}},"example":{"profileId":"507f1f77bcf86cd799439011","country":"DE"}}}},"responses":{"200":{"description":"Either a checkout URL (first number) or the provisioned phone number (subsequent numbers).\n","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Checkout session created (first number)","properties":{"message":{"type":"string"},"checkoutUrl":{"type":"string","format":"uri"}}},{"type":"object","description":"Phone number provisioned inline (subsequent numbers)","properties":{"message":{"type":"string"},"phoneNumber":{"type":"object","properties":{"id":{"type":"string"},"phoneNumber":{"type":"string"},"status":{"type":"string"},"country":{"type":"string"},"provisionedAt":{"type":"string","format":"date-time"},"metaPreverifiedId":{"type":"string"},"metaVerificationStatus":{"type":"string"}}}}},{"type":"object","description":"A number was already purchased under the supplied purchaseIntentId; no new number was provisioned.\n","properties":{"status":{"type":"string","enum":["already_purchased"]},"numberId":{"type":"string"},"phoneNumber":{"type":"string"}}}]}}}},"202":{"description":"Country requires end-user KYC before the number can be ordered.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["kyc_required"]},"country":{"type":"string"},"numberType":{"type":"string","description":"The type that will be ordered after KYC approval."},"kycUrl":{"type":"string"}}}}}},"400":{"description":"Plan limit reached, profileId required, or country not available"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"A payment method is required because the usage-based account has no card on file: add a card, then retry.","description":"Payment method required (usage-based billing account with no card on file): code PAYMENT_REQUIRED, add a card, then retry. On balance billing with the balance at $0: code insufficient_balance or usage_limit_reached, top up in Billing, then retry."},"403":{"description":"A paid plan is required"},"409":{"x-summary":"The request hit duplicate-purchase protection or lacks stock: retry with `allowMultiple`, or pick another area, number or country.","description":"Conflict: duplicate-purchase protection, or no deliverable inventory for the request. Codes:\n\n- PURCHASE_VELOCITY: another number was purchased within the last 10 minutes. Retry with allowMultiple: true to confirm.\n- AREA_CODE_UNAVAILABLE: the requested areaCode has no deliverable inventory right now. Pick another area or omit areaCode.\n- PHONE_NUMBER_UNAVAILABLE: search again and pick another number.\n- COUNTRY_OUT_OF_STOCK: this country and type have no orderable numbers right now. Pick another.\n- NO_WHATSAPP_ELIGIBLE_NUMBER: every number the carrier offered is one WhatsApp refuses. Pass an areaCode or try again for a fresh batch.\n","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["PURCHASE_VELOCITY","AREA_CODE_UNAVAILABLE","PHONE_NUMBER_UNAVAILABLE","COUNTRY_OUT_OF_STOCK","NO_WHATSAPP_ELIGIBLE_NUMBER"]}}}}}},"422":{"x-summary":"International numbers require usage-based billing, and legacy Stripe users are limited to the US: switch to usage-based billing.","description":"International numbers require usage-based billing (legacy Stripe users are US-only). Response body code: USAGE_BILLING_REQUIRED."},"503":{"description":"The carrier could not take the order just now (code CARRIER_UNAVAILABLE); the number is not taken, retry the same request in a minute.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["CARRIER_UNAVAILABLE"]}}}}}}}}},"/v1/whatsapp/phone-numbers/countries":{"get":{"x-resource-group":"telephony","operationId":"listWhatsAppNumberCountries","deprecated":true,"tags":["WhatsApp Phone Numbers"],"summary":"List offerable number countries","description":"Deprecated alias of `/v1/phone-numbers/countries`; same contract. New\nintegrations should use that path.\n\nThe WhatsApp number countries available to purchase, each with its flat\nmonthly price (cents), regulatory tier, whether it needs end-user KYC\n(Tier 3/4), and whether outbound calling is available (not BIC-blocked).\nDrives the country picker. Tier-4 countries appear only when enabled.\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Offerable countries, cheapest first.","content":{"application/json":{"schema":{"type":"object","properties":{"countries":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"ISO 3166-1 alpha-2"},"tier":{"type":"integer","enum":[1,2,3,4]},"monthlyCents":{"type":"integer","description":"Price a NEW number in this country costs per month, in cents, for the default (first) type. 1.5x the carrier's monthly cost, rounded up to a whole dollar, minimum $3."},"needsKyc":{"type":"boolean"},"outboundCallingAvailable":{"type":"boolean"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/whatsapp/phone-numbers/available":{"get":{"x-resource-group":"telephony","operationId":"searchAvailableWhatsAppNumbers","deprecated":true,"tags":["WhatsApp Phone Numbers"],"summary":"Search available numbers","description":"Deprecated alias of `/v1/phone-numbers/available`; same contract. New\nintegrations should use that path.\n\nSearch the provider's inventory for numbers available to purchase in a\ncountry (default US). Optional filters narrow the results. The country\nmust be offerable (see GET /v1/whatsapp/phone-numbers/countries).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"US"}},{"name":"numberType","in":"query","required":false,"description":"Number type; defaults to the country's WhatsApp-safe type (the same name as on purchase, availability and kyc)","schema":{"type":"string","enum":["local","mobile","national","toll_free"]}},{"name":"areaCode","in":"query","required":false,"description":"Area code or national dialing code the number must start with, e.g. 415 or 91","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"deprecated":true,"description":"Alias of numberType, kept for existing callers","schema":{"type":"string"}},{"name":"prefix","in":"query","required":false,"deprecated":true,"description":"Alias of areaCode, kept for existing callers","schema":{"type":"string"}},{"name":"locality","in":"query","required":false,"description":"A city name, matched against the numbering plan (accents and common aliases allowed) and searched by that city's area codes; a name no city of the plan matches returns no numbers. `areaCode` takes a city name too.","schema":{"type":"string"}},{"name":"contains","in":"query","required":false,"description":"Pattern to match within the number","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Available numbers.","content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string"},"numberType":{"type":"string"},"numbers":{"type":"array","items":{"type":"object","properties":{"phoneNumber":{"type":"string"},"locality":{"type":"string"},"bestEffort":{"type":"boolean"}}}}}}}}},"400":{"x-summary":"The country is not offerable, the numberType is not offered, or the request has an unknown query parameter: fix the request.","description":"Country not offerable, numberType outside the four offered, or a query parameter this endpoint does not know (the message lists the accepted ones; nothing is silently ignored)."},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/whatsapp/phone-numbers/availability":{"get":{"x-resource-group":"telephony","operationId":"checkWhatsAppNumberAvailability","deprecated":true,"tags":["WhatsApp Phone Numbers"],"summary":"Check country availability","description":"Deprecated alias of `/v1/phone-numbers/availability`; same contract. New integrations should use that path.\n\nA pre-purchase check, so you can warn BEFORE a customer invests in KYC (regulated review is async, 1-3 days). It tells you whether we have deliverable inventory, and what address the customer needs. Call this before starting the KYC form for regulated countries.\n\n### Address constraints\n\n- `addressConstraint: geo`: the registered address MUST be in one of the returned `areas` (the only place we have stock). A different-area address passes pre-approval but the number can never be assigned.\n- `addressConstraint: country`: any in-country address works.\n- `addressConstraint: none`: field-only / instant country, no address.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"country","in":"query","required":true,"schema":{"type":"string"},"description":"ISO-2 country code."},{"name":"numberType","in":"query","required":false,"schema":{"type":"string","enum":["local","mobile","national","toll_free"]},"description":"Check a specific offered type (stock and address constraints are per type). Omitted = the country's default type."},{"name":"sms","in":"query","required":false,"schema":{"type":"boolean"},"description":"Pass true when the buyer wants SMS: availability, areas, and areaOptions then describe the SMS-capable pool (an SMS purchase orders from it), not the wider voice-only pool."}],"responses":{"200":{"description":"Availability + address constraint.","content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string"},"numberType":{"type":"string"},"available":{"type":"boolean","description":"Whether deliverable voice inventory exists right now."},"preOrderable":{"type":"boolean","description":"Nothing deliverable now, but this pair can be pre-ordered: submit KYC as usual and we buy regular stock the moment it returns, otherwise the carrier sources the number (usually 2 to 4 weeks, never guaranteed). Only document tiers (3/4) qualify."},"addressConstraint":{"type":"string","enum":["geo","country","none"]},"areas":{"type":"array","description":"For `geo` only: the area(s) the registered address must be in.","items":{"type":"string"}},"areaOptions":{"type":"array","description":"Live inventory grouped by area code. Equal to `areaAvailability.inStock`. Empty when out of stock (or the area lookup failed).\n\n- **US and CA:** the full country inventory (every area code with stock, recognizable metros first, then alphabetical).\n- **Other countries:** largest stock first, listing the areas in the latest inventory page (up to 500 numbers, for most countries the entire pool).\n\nPass a chosen `ndc` as `areaCode` on POST /v1/phone-numbers/purchase (or on the KYC submit for regulated countries) to require that area.\n","items":{"type":"object","properties":{"ndc":{"type":"string","description":"Area code (national destination code), e.g. \"11\"."},"name":{"type":"string","description":"Area name: \"City, ST\" for US/CA (e.g. \"Miami, FL\"), city otherwise (e.g. \"Sao Paulo\")."},"count":{"type":"integer","description":"Numbers available in this area: country-wide count for US/CA, numbers seen on the latest inventory page otherwise."}}}},"soldOutAreas":{"type":"array","description":"Every area of the country's numbering plan with nothing deliverable now: `areaAvailability.preOrder` plus `areaAvailability.outOfStock`, kept for older clients. Pass one as `areaCode` with `preOrder: true` on the KYC submit when `preOrderable` is true, or watch it with POST /v1/phone-numbers/stock-watches.\n","items":{"type":"object","properties":{"ndc":{"type":"string","description":"Area code (national destination code)."},"name":{"type":"string","description":"Area name."},"preOrderable":{"type":"boolean","description":"Whether this area can be pre-ordered: the carrier sources a number in it (usually 2 to 4 weeks, never guaranteed)."}}}},"areaAvailability":{"type":"object","description":"Every area of the country's numbering plan (Google libphonenumber geocoding, one row per city: Madrid covers 910 to 919), in one of three states.\n\nRefreshed every 6 hours from the carrier's own inventory counts. The same answer the dashboard picker and the public country pages show. Empty lists mean the pair has no cached coverage yet, not that the country has no areas.\n","properties":{"inStock":{"type":"array","description":"Deliverable numbers now, deepest first. Pass `ndc` as `areaCode` to hold the order to it.","items":{"type":"object","properties":{"ndc":{"type":"string"},"name":{"type":"string"},"count":{"type":"integer","description":"Numbers we can sell there: the carrier count minus the numbers we hold back (WhatsApp refused them or another order holds them)."},"ndcs":{"type":"array","items":{"type":"string"},"description":"Every area code of the city, deepest first (Madrid: 915, 911, 910, ...). `ndc` is the one an order is placed against."},"aliases":{"type":"array","items":{"type":"string"},"description":"Other names the area answers to, present only when it has some (Milano for Milan, Sevilla for Seville)."}}}},"preOrder":{"type":"array","description":"The carrier lists nothing there and the number type is a document tier: submit KYC with `areaCode` and `preOrder: true`, the carrier sources one (usually 2 to 4 weeks, never guaranteed), nothing is billed until it is active.","items":{"type":"object","properties":{"ndc":{"type":"string"},"name":{"type":"string"},"ndcs":{"type":"array","items":{"type":"string"},"description":"Every area code of the city, deepest first (Madrid: 915, 911, 910, ...). `ndc` is the one an order is placed against."},"aliases":{"type":"array","items":{"type":"string"},"description":"Other names the area answers to, present only when it has some (Milano for Milan, Sevilla for Seville)."}}}},"outOfStock":{"type":"array","description":"Nothing deliverable and no pre-order: `listed` > 0 is stock the carrier shows that WhatsApp refused recently (held back until it clears), 0 is a dry area of an instant tier. A stock watch (POST /v1/phone-numbers/stock-watches with `areaCode`) is the way to hear when it is back.","items":{"type":"object","properties":{"ndc":{"type":"string"},"name":{"type":"string"},"listed":{"type":"integer"},"ndcs":{"type":"array","items":{"type":"string"},"description":"Every area code of the city, deepest first (Madrid: 915, 911, 910, ...). `ndc` is the one an order is placed against."},"aliases":{"type":"array","items":{"type":"string"},"description":"Other names the area answers to, present only when it has some (Milano for Milan, Sevilla for Seville)."}}}}}}}}}}},"400":{"description":"Country not offerable, or the inventory provider rejected the lookup (its 4xx status is forwarded as-is)."},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"description":"The inventory provider was unreachable or returned an unclassified error."}}}},"/v1/phone-numbers/kyc":{"get":{"x-resource-group":"telephony","operationId":"getPhoneNumberKycForm","tags":["Phone Numbers"],"summary":"Get KYC form spec","description":"For a Tier 3/4 country, the fields the end customer must provide (Telnyx\nregulatory requirements) before a number can be ordered: text, date,\naddress, or file (document) per requirement.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"country","in":"query","required":true,"schema":{"type":"string"}},{"name":"numberType","in":"query","required":false,"schema":{"type":"string","enum":["local","mobile","national","toll_free"]},"description":"Requirements and reuse eligibility are per (country, type). Omitted = the country's default type. Pass the same value on the POST."}],"responses":{"200":{"description":"The KYC form spec.","content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string"},"numberType":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"requirementId":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string","enum":["text","date","address","file","action"],"description":"\"action\" = an out-of-band verification (e.g. Onfido); not filled here, fulfilled after the order via a link."},"description":{"type":["string","null"],"description":"Plain-English explanation of what to provide."},"example":{"type":["string","null"],"description":"Concrete example value."},"localTo":{"type":["string","null"],"description":"ISO country the value must be local to"}}}},"reusable":{"type":["object","null"],"description":"Present when this account already has a reusable verification for the country (skip the form).\n\n- `fromPhoneNumber`/`details` mirror the first option.\n- `options` lists ALL reusable verifications (agencies hold one per end client), approved-first. Pass the chosen option's `id` as `reuseOptionId` on POST.\n- Each option's `instant` says whether it activates in minutes (group-approved) or still queues for carrier review (1-3 days).\n","properties":{"available":{"type":"boolean"},"fromPhoneNumber":{"type":"string"},"details":{"type":"array","description":"Human-readable summary of the verification on file (field labels + values, plus the address as one line). Best-effort. May be empty if the provider lookup fails.","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}}}},"options":{"type":"array","description":"One entry per distinct approved verification, newest first.","items":{"type":"object","properties":{"id":{"type":"string","description":"Opaque option id. Pass as `reuseOptionId` on POST. Stable selection key (a phone number is not unique across verifications)."},"fromPhoneNumber":{"type":"string","description":"Display only. The number this verification was submitted for. Not a selection key."},"instant":{"type":"boolean","description":"true = group-approved, a new order activates in minutes; false = documents are reused but the order still queues for carrier review (1-3 days)."},"details":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"},"documentId":{"type":"string","description":"Present on document rows: the Telnyx document id. GET /v1/whatsapp/phone-numbers/kyc/document/{documentId} streams it (auth-scoped, inline PDF)."}}}}}}}}},"pendingReview":{"type":"boolean","description":"true when this account already has a number for this country in regulatory review (status pending_regulatory).\n\n- Scope is the whole account across all profiles, and the country only (any number type), so it is not a per-end-client signal on a multi-tenant setup.\n- Informational only: it never blocks a submission, and several same-country numbers may sit in review at once.\n\nFor a per-end-client view, call GET /v1/phone-numbers with `profileId` and `status=pending_regulatory`; that view also lists numbers declined in the last 30 days."}}}}}},"400":{"description":"Country not available"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"x-resource-group":"telephony","operationId":"submitPhoneNumberKyc","tags":["Phone Numbers"],"summary":"Submit KYC","description":"Submit the end customer's KYC (textual values, uploaded documents, address) for a Tier 3/4 country. Documents are streamed straight to the number provider and are not stored by Zernio.\n\nThe call builds + submits a regulatory requirement group and claims a pending_regulatory slot. The number is ordered + activated once the provider approves (asynchronous).\n\nA customer may hold several same-country numbers in review at once. A double-submit of the SAME attempt is deduped via `submissionId`.\n\n### ID documents\n\nFor an ID-card document requirement, carriers commonly require BOTH sides. Combine the front and back into a single file before uploading (the dashboard does this automatically).\n\nA one-sided ID is a common decline reason; fix it via POST /v1/phone-numbers/{id}/remediate.\n\n### Before submitting\n\nCall GET /v1/phone-numbers/availability to check the country has deliverable inventory and, for geographic-match countries, which area the address must be in. Otherwise the submission can pass review yet never be assignable a number.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","country"],"properties":{"profileId":{"type":"string"},"country":{"type":"string"},"submissionId":{"type":"string","description":"Idempotency token for this submission attempt. Omit it and every call provisions a new number.\n\n- Once the number has been ordered, a retry with the same token returns that number instead of ordering another.\n- A submission that fails before the number is ordered releases the token, so you can correct your details and re-submit with it."},"quantity":{"type":"integer","minimum":1,"maximum":5,"default":1,"description":"Provision several same-country numbers from one submission (1-5). The single verification covers all of them; each number is billed only when it activates. Numbers that fail to order are skipped (best-effort). With `areaCode`, a quantity above that area's live stock is rejected with a 400."},"reuse":{"type":"boolean","description":"Reuse a prior approved verification for this country (skips document/field collection; places the order immediately)."},"reuseOptionId":{"type":"string","description":"Which reusable verification to use (GET reusable.options[].id). The unambiguous selection key. Omitted = the approved default. No match = 409."},"reuseFrom":{"type":"string","description":"Legacy fallback for `reuseOptionId`: the source phone number (GET reusable.options[].fromPhoneNumber). Ambiguous when a number labels two verifications, so prefer `reuseOptionId`. Omitted = the approved default. No match = 409."},"areaCode":{"type":"string","pattern":"^\\d{1,4}$","description":"Area code (NDC) the number must be in. Omit for any area.\n\nHard constraint: an empty area pool fails with 409 code AREA_CODE_UNAVAILABLE instead of ordering from another area.\n\nOptions come from GET /v1/phone-numbers/availability (areaOptions). The purchase 202 kycUrl echoes the areaCode picked at purchase time so it can be passed here."},"phoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"Exact number to order, in E.164, taken from GET /v1/phone-numbers/available. It is ordered as is or the request fails with 409 code phone_number_unavailable; another number is never substituted and a pre-order is never placed. Requires quantity 1 (or omitted). Omit to let the carrier pick a number in the area."},"preOrder":{"type":"boolean","description":"Pre-order a number when the requested area has no stock.\n\n- With areaCode: pre-order that area when it has no stock (listed in soldOutAreas with preOrderable true) instead of failing with AREA_CODE_UNAVAILABLE. The carrier sources a number in that area.\n- Without areaCode: accepts the pre-order a previous submit offered with 409 code area_pre_order_available (a geographic-match country whose address area has no stock). Resend the same body with preOrder true and the order is placed for that area.\n\nA whole pair with no stock is pre-ordered without either flag."},"endUserFirstName":{"type":"string","description":"End user's legal first name. Required when the country has an action/ID-verification (Onfido) requirement."},"endUserLastName":{"type":"string","description":"End user's legal last name. Same condition as endUserFirstName."},"values":{"type":"object","additionalProperties":{"type":"string"},"description":"requirementId → textual value"},"documents":{"type":"array","description":"One per document requirement. Each is EITHER inline base64 OR a `documentId` returned by POST /v1/phone-numbers/kyc/upload-document (use the upload endpoint for large files to stay under the request-size limit).","items":{"oneOf":[{"type":"object","required":["requirementId","filename","base64"],"properties":{"requirementId":{"type":"string"},"filename":{"type":"string"},"base64":{"type":"string"}}},{"type":"object","required":["requirementId","documentId"],"properties":{"requirementId":{"type":"string"},"documentId":{"type":"string","description":"Id from POST /v1/phone-numbers/kyc/upload-document."},"issuedAt":{"type":"string","format":"date","description":"Date printed on the document (YYYY-MM-DD), for slots the regulator windows such as proof of address. The pre-submit review trusts it over its own read of the PDF."}}}]}},"address":{"type":"object","properties":{"requirementId":{"type":"string"},"country_code":{"type":"string"},"business_name":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"street_address":{"type":"string"},"extended_address":{"type":"string","description":"Address complement: apartment, suite, unit, or the quadra/lote used in some countries. Optional. Does not substitute for a building number on street_address."},"locality":{"type":"string"},"administrative_area":{"type":"string"},"postal_code":{"type":"string"}}}}}}}},"responses":{"200":{"description":"KYC submitted (or already submitted); number pending review.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["kyc_submitted","kyc_reused","kyc_already_submitted"]},"preOrder":{"type":"boolean","description":"True when this submission placed a pre-order instead of an order from stock. That happens when:\n\n- the country and type had nothing deliverable;\n- the picked areaCode was sold out (preOrder: true sent); or\n- the country requires the number's area to cover the registered address, that area has no stock, and the caller accepted the offer (preOrder true after a 409 area_pre_order_available). The carrier is then asked for a number in exactly that area.\n\nThe number stays `pending_regulatory` until we get it, from regular stock the moment it returns or sourced by the carrier (usually 2 to 4 weeks, never guaranteed). It is not billed until active.\n\nReleasing it (DELETE /v1/phone-numbers/{id}) cancels the pre-order. A pre-order is one number: `quantity` above 1 is rejected with 400."},"phoneNumber":{"type":"object","description":"The first/primary number, kept at the top level for backward compatibility. See `numbers` for the full set when `quantity` > 1.","properties":{"id":{"type":"string"},"status":{"type":"string"},"country":{"type":"string"}}},"numbers":{"type":"array","description":"Every number provisioned from this submission. Length equals the requested `quantity` on full success (fewer if some orders failed; best-effort). The first element mirrors `phoneNumber`.","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"phoneNumber":{"type":"string"},"country":{"type":"string"}}}}}}}}},"400":{"description":"Validation error (e.g. address not in-country, file too large)"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"x-summary":"Nothing was created because the area or number has no stock: resend with `preOrder` when offered, or pick another area or number.","description":"Conflict. The `code` says which case:\n\n- **area_pre_order_available:** the country requires the number to cover the registered address and that area has no stock, but the carrier can source one. Nothing was created. details carries { areaCode, areaName, estimatedWeeks: \"2-4\", billedWhenActive: true }.\n- **area_pre_order_available, next step:** show it to the customer and, once they agree, resend the same body with preOrder true (optionally with details.areaCode as areaCode).\n- **area_code_unavailable:** the requested areaCode (or, in a geographic-match country, the area covering the registered address) has no deliverable inventory and cannot be pre-ordered. Pick another area, or a registered address in an area with stock.\n- **country_out_of_stock:** the whole country and type pool has nothing deliverable and cannot be pre-ordered. Choose an area with stock or set a stock watch.\n- **phone_number_unavailable** (param phoneNumber): phoneNumber was sent and that exact number is no longer available (or WhatsApp cannot use it). Nothing was ordered; pick another number.\n- **Reuse with no prior verification:** reuse was requested but no prior approved verification exists for this country.\n\nWhen the only numbers the carrier lists recently failed WhatsApp registration and are held back, the message names the date the first one clears, and details.undeliverableUntil carries it as an ISO timestamp."}}}},"/v1/phone-numbers/kyc/document/{documentId}":{"get":{"x-resource-group":"telephony","operationId":"viewPhoneNumberKycDocument","tags":["Phone Numbers"],"summary":"View a KYC document on file","description":"Stream a document backing a reusable verification, so the account holder can see what's on file before reusing it. The ids are the `documentId` values from GET /v1/phone-numbers/kyc `reusable.options[].details[]`.\n\nReturned inline as `application/pdf` (uploads are normalized to PDF).\n\nAuth-scoped: a document is viewable only when its id is referenced by one of the caller's own numbers. Otherwise `404`.\n","parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"},"description":"The Telnyx document id (from `reusable.options[].details[].documentId`)."}],"responses":{"200":{"description":"The document, streamed inline.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No such document for this account."}}}},"/v1/phone-numbers/kyc/upload-document":{"post":{"x-resource-group":"telephony","operationId":"uploadPhoneNumberKycDocument","tags":["Phone Numbers"],"summary":"Upload a KYC document","description":"Upload ONE document and get back its provider document id, to reference from POST /v1/phone-numbers/kyc via `documents[].documentId`.\n\n- Send the RAW file bytes as the request body (not base64).\n- Put the filename in the `X-Filename` header.\n- Uploading documents one-per-request keeps each request under the ~4.5MB body limit.\n\nThe document streams straight to the number provider and is not stored by Zernio.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"X-Filename","in":"header","required":true,"schema":{"type":"string"},"description":"URL-encoded original filename."}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Document uploaded.","content":{"application/json":{"schema":{"type":"object","properties":{"documentId":{"type":"string","description":"Reference this id in the KYC submit's documents[].documentId."}}}}}},"400":{"description":"Missing X-Filename, empty body, or file too large (over 20MB)."},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/phone-numbers/kyc/validate-address":{"post":{"x-resource-group":"telephony","operationId":"validatePhoneNumberKycAddress","tags":["Phone Numbers"],"summary":"Pre-validate KYC address","description":"Optional early check for the address step of a Tier 4 (end-user identity) registration. It validates a postal address for deliverability BEFORE the full KYC submit, so it can be corrected before any documents are uploaded.\n\nThe full submit (POST /v1/phone-numbers/kyc) re-validates the address, so this call is purely a fast feedback path and skipping it is safe.\n\nOnly the postal address is sent (no documents, no gov-ID fields).\n\nA region (`administrative_area`) is required by the validator. When it is omitted the pre-check is skipped and `{ ok: true, skipped: true }` is returned (the final submit still validates).\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["country","street_address","locality","postal_code"],"properties":{"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country code."},"street_address":{"type":"string"},"extended_address":{"type":"string","description":"Address complement: apartment, suite, unit, or the quadra/lote used in some countries. Optional. Does not substitute for a building number on street_address."},"locality":{"type":"string","description":"City / town."},"administrative_area":{"type":"string","description":"State / province / region. When omitted, the pre-check is skipped (the final submit still validates)."},"postal_code":{"type":"string"}}}}}},"responses":{"200":{"description":"Address is deliverable, or the pre-check was skipped (no region supplied).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"skipped":{"type":"boolean","description":"true when no `administrative_area` was supplied, so no pre-check ran."}}}}}},"400":{"x-summary":"The country is not offered or the address could not be verified: apply the suggested corrections from the error details when present.","description":"The country isn't offered, or the address could not be verified. When the\nprovider returned usable corrections, `details.addressSuggestions` carries\nthem per field for a one-click \"apply suggestion\" card. (Flat error\nenvelope: `error` is the human message; `code`/`param`/`details` are\ntop-level siblings.)\n","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message."},"type":{"type":"string"},"code":{"type":"string","example":"INVALID_FIELD_VALUE"},"param":{"type":"string","example":"address"},"details":{"type":"object","properties":{"addressSuggestions":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","example":"administrative_area"},"label":{"type":"string","example":"State / Province"},"value":{"type":"string","example":"Dublin"}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/phone-numbers/kyc/share":{"post":{"x-resource-group":"telephony","operationId":"createPhoneNumberKycLink","tags":["Phone Numbers"],"summary":"Create a hosted KYC link","description":"Create a single-use, 7-day hosted KYC link that your end customer completes WITHOUT a Zernio login. Useful when the person who holds the ID and address is not your team.\n\nThey fill the regulated verification on a Zernio-hosted page, and the number provisions under YOUR account once they submit. Only regulated (KYC) countries are valid: a country that does not require KYC returns 400.\n\n### Choosing the number\n\n- `numberType` (`local`, `mobile`, `national`, `toll_free`): which of the country's offered types the shared form collects KYC for and eventually orders. Omitted, it defaults to the country's default type, which may be `national` and therefore have no inventory in a geographic area code.\n- `areaCode` (NDC digits): constrains the eventual order to a specific area. It is validated against the chosen `numberType`.\n\n### Branding and completion\n\n- White-label the page with `branding` (your company name, logo, brand color).\n- Supply `redirect_url` to send the end customer back to your own site after a successful submit (completion params are appended; see below).\n- Listen for the `whatsapp.number.kyc_submitted` webhook to react when the form is completed.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","country"],"properties":{"profileId":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country code (must be a regulated/KYC country)."},"areaCode":{"type":"string","pattern":"^\\d{1,4}$","description":"Area code (NDC) the eventual number must be in. Hard constraint carried by the link; the end customer filling the form makes no area choice. Options come from GET /v1/phone-numbers/availability (areaOptions)."},"language":{"type":"string","enum":["en","es","pt-BR"],"description":"Language of the hosted page: its copy, the carrier requirement texts (translated once per country and cached), the pre-submit review notes and the status emails to the end customer.\n\nOmitted: the browser language of the end customer, falling back to English. The end customer can also switch with `?lang=` on the page.\n"},"branding":{"type":"object","description":"Optional white-label of the hosted page the end customer sees.","properties":{"companyName":{"type":"string","maxLength":60,"description":"Your company name, shown on the hosted page."},"logoUrl":{"type":"string","format":"uri","description":"Logo shown above the form."},"brandColor":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","description":"Hex color (e.g. #1a73e8) used as a brand accent on the page."}}},"redirect_url":{"type":"string","format":"uri","description":"Where to send the end customer's browser after a successful\nsubmit. On completion Zernio appends `kyc=submitted` and\n`country=<ISO-2>` as query params. When omitted, the hosted\npage shows a built-in confirmation screen instead.\n"}}}}}},"responses":{"200":{"description":"Hosted KYC link created.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"The hosted link to send your end customer."},"token":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Country does not require KYC (not a regulated country)."},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/phone-numbers/port-in":{"post":{"x-resource-group":"telephony","operationId":"createPhoneNumberPortIn","tags":["Phone Numbers"],"summary":"Port numbers in","description":"Submit a port-in for one or more existing numbers from another carrier.\n\nThe call creates the carrier order(s), attaches the end-user (current account) info plus the LOA and invoice documents, and submits to the losing carrier. The transfer PIN is forwarded to the carrier and never stored.\n\nPorted numbers arrive voice-ready (and SMS-ready where the order supports messaging).\n\n### Before calling\n\n1. Run the portability check (POST /v1/phone-numbers/port-in/check).\n2. Upload the two documents (POST /v1/phone-numbers/port-in/documents) right before this call. Uploaded documents must be attached to an order within 30 minutes or the carrier deletes them.\n\n### Orders and partial failures\n\nThe carrier may split the numbers into several orders (by country, number type, losing carrier). `orders` carries per-order results.\n\nA partial failure still returns 201 with the failed orders' `error` set (they stay as cancellable drafts).\n\n### Non-US/CA numbers\n\nThese additionally need the country-specific values from GET /v1/phone-numbers/port-in/requirements, passed via `requirements`, and must be submitted one country per request.\n\nWhen required information is still missing after submission, the order is kept as a resumable draft whose `error` / `declineReason` names the gaps.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phoneNumbers","endUser","loaDocumentId","invoiceDocumentId"],"properties":{"phoneNumbers":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"},"description":"E.164 numbers to port in."},"endUser":{"type":"object","description":"End-user / current-carrier account info that authorizes the port. The\nlosing carrier matches every field against its records and rejects the\nwhole port on a mismatch, so enter values exactly as they appear on the\ncarrier bill.\n","required":["entityName","authPersonName","accountNumber","streetAddress","locality","postalCode","countryCode"],"properties":{"entityName":{"type":"string","description":"Account holder / business name, as on the carrier account."},"authPersonName":{"type":"string","description":"Full name (first + last) of the person authorizing the port, which must match the LOA signature."},"billingPhoneNumber":{"type":"string","description":"Phone number on the losing carrier's bill. Defaults to the ported number itself on single-number orders. Validated as a real phone number when present."},"accountNumber":{"type":"string","description":"Account number with the losing carrier. Required (carriers reject ports without it; on prepaid mobile plans it is often the phone number itself)."},"pinPasscode":{"type":"string","description":"Transfer PIN. Required for US/CA mobile numbers (wireless carriers reject PIN-less ports). Forwarded to the carrier, never stored. International porting codes (e.g. the UK PAC) go through `requirements` instead."},"taxIdentifier":{"type":"string","maxLength":50,"description":"Company tax id on the carrier account (EU ports, e.g. Spanish CIF)."},"businessIdentifier":{"type":"string","maxLength":50,"description":"Business registration id on the carrier account (EU ports)."},"streetAddress":{"type":"string"},"extendedAddress":{"type":"string"},"locality":{"type":"string"},"administrativeArea":{"type":"string","description":"Region. Required for US/CA as the 2-letter state/province code (full names are accepted and normalized); optional elsewhere."},"postalCode":{"type":"string","description":"Postal code. Validated as a US ZIP / Canadian postal code for US/CA; free-form elsewhere."},"countryCode":{"type":"string","minLength":2,"maxLength":2,"enum":["US","CA","GB","ES","DE","FR","NL","AU","BR"],"description":"Service-address country (a supported port-in country)."}}},"loaDocumentId":{"type":"string","description":"Document id from POST /v1/phone-numbers/port-in/documents (kind=loa)."},"invoiceDocumentId":{"type":"string","description":"Document id from POST /v1/phone-numbers/port-in/documents (kind=invoice)."},"focDatetimeRequested":{"type":"string","format":"date-time","description":"Requested port date; the carrier confirms the actual FOC later. US/CA default is one week out (shifted off weekends); international orders are scheduled into the carrier's next allowed porting window at or after this date."},"customerReference":{"type":"string","maxLength":100},"portType":{"type":"string","enum":["full","partial"],"default":"full","description":"Whether the losing account ports all its numbers (full) or keeps some (partial)."},"requirements":{"type":"array","maxItems":30,"description":"Country-specific requirement values for international ports (from GET /v1/phone-numbers/port-in/requirements). Not needed for US/CA. The LOA and invoice requirements are satisfied automatically by loaDocumentId/invoiceDocumentId, and address-type requirements by the endUser service address.","items":{"type":"object","required":["requirementTypeId","fieldValue"],"properties":{"requirementTypeId":{"type":"string","description":"The requirement's id, from the requirements endpoint."},"fieldValue":{"type":"string","maxLength":1000,"description":"Text value, ISO datetime, or a documentId from POST /v1/phone-numbers/port-in/documents, per the requirement's kind."}}}}}}}}},"responses":{"201":{"x-summary":"The port-in was submitted: top-level fields mirror the first submitted order, so read `orders` for the result of each order.","description":"Port submitted. Top-level fields mirror the first successfully submitted order; per-order truth (including failures) is in `orders`.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Porting order ID."},"telnyxPortingOrderId":{"type":"string"},"status":{"type":"string","enum":["draft","pending","foc_confirmed","ported","exception","cancelled"]},"phoneNumbers":{"type":"array","items":{"type":"string"}},"orders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"telnyxPortingOrderId":{"type":"string"},"status":{"type":"string"},"phoneNumbers":{"type":"array","items":{"type":"string"}},"error":{"type":"string","description":"Present when this split order failed to submit (it stays as a cancellable draft)."}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"description":"A number is already provisioned, or already in an in-flight port"},"422":{"description":"A number is not portable (reason included), numbers span multiple non-US/CA countries, or every split order failed to submit"}}},"get":{"x-resource-group":"telephony","operationId":"listPhoneNumberPortIns","tags":["Phone Numbers"],"summary":"List port-in orders","description":"Your porting orders, newest first (max 50). Poll this for port progress:\npending, confirmed FOC date, exception reason, or ported.\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Porting orders","content":{"application/json":{"schema":{"type":"object","properties":{"orders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["draft","pending","foc_confirmed","ported","exception","cancelled"]},"telnyxStatusValue":{"type":["string","null"],"description":"Raw carrier status string."},"phoneNumbers":{"type":"array","items":{"type":"string"}},"fastPortEligible":{"type":["boolean","null"]},"focDatetimeRequested":{"type":["string","null"],"format":"date-time"},"focDatetimeActual":{"type":["string","null"],"format":"date-time"},"declineReason":{"type":["string","null"]},"submittedAt":{"type":["string","null"],"format":"date-time"},"portedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/phone-numbers/port-in/check":{"post":{"x-resource-group":"telephony","operationId":"checkPhoneNumberPortability","tags":["Phone Numbers"],"summary":"Check portability","description":"Pre-flight portability check, BEFORE the user commits to a port order (LOA, invoice, service address). For each number it returns:\n\n- whether it can be ported in\n- whether it qualifies for FastPort\n- its current carrier and line type, where the carrier lookup knows them\n\nRead-only; creates no order and bills nothing.\n\n### Keyless calls\n\nWorks without an API key for one number per request. Keyless calls are what the checker at https://zernio.com/port-your-number makes. Because each check runs a paid carrier lookup, they are limited:\n\n- they must come from that page (a browser bot check rejects scripted callers with 401)\n- per IP: 3 a minute, 10 a day\n- by a shared daily budget (429 once spent)\n\nEach portable keyless result carries a `claimId` and a `claimUrl`: a signup link that opens the dashboard's port form with the number filled in.\n\n### With an API key\n\nSend an API key to check up to 50 numbers without those limits.\n","security":[{},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phoneNumbers"],"properties":{"phoneNumbers":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"},"description":"E.164 numbers to check, e.g. +13035550000. At most one without an API key."},"claimLinks":{"type":"boolean","description":"true adds `claimId` and `claimUrl` to portable results even when you send an API key, e.g. to hand a user a signup link that opens the port form with their number."}}}}}},"responses":{"200":{"description":"Per-number portability.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"phoneNumber":{"type":"string"},"portable":{"type":"boolean"},"fastPortable":{"type":"boolean","description":"Qualifies for the carrier's accelerated FastPort lane."},"messagingCapable":{"type":["boolean","null"],"description":"Whether texting can be enabled on the number once ported; null when the carrier does not say."},"lineType":{"type":["string","null"],"description":"Line type when known (mobile, landline, voip, toll-free, unknown). US/CA portable numbers only. A US/CA mobile number requires the transfer PIN at submit."},"carrierName":{"type":["string","null"],"description":"The number's current carrier, when the lookup knows it. US/CA portable numbers only."},"countryCode":{"type":["string","null"],"description":"ISO country of the number. Pass it to GET /v1/phone-numbers/port-in/requirements for international numbers."},"phoneNumberType":{"type":["string","null"],"description":"Carrier number-type classification (local, mobile, national, toll_free...), the numberType for the requirements endpoint."},"notPortableReason":{"type":["string","null"],"description":"Carrier reason when not portable; null when portable."},"claimId":{"type":"string","description":"Keyless calls and claimLinks=true only, on portable results. Resolve it with GET /v1/phone-numbers/port-in/claims/{claimId}. Expires after 7 days."},"claimUrl":{"type":"string","description":"Keyless calls and claimLinks=true only, on portable results. A signup link that lands on the dashboard's port form with this number filled in."}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"x-summary":"The per-IP limit or shared daily budget for keyless calls is spent: wait for `Retry-After`, or send an API key.","description":"Keyless calls only. The per-IP limit or the shared daily budget is spent; `Retry-After` says when to try again. Send an API key to skip both."}}}},"/v1/phone-numbers/port-in/claims/{claimId}":{"get":{"x-resource-group":"telephony","operationId":"getPhoneNumberPortClaim","tags":["Phone Numbers"],"summary":"Resolve a port claim","description":"Resolves a `claimId` from a keyless portability check into the number\nit carries. The dashboard calls it when a person lands from a port\n`claimUrl`, to open the port form with that number filled in. It does\nnot start a port.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"claimId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The claimed number.","content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumber":{"type":"string","description":"E.164."},"countryCode":{"type":["string","null"],"description":"ISO country of the number."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"The claim expired (after 7 days) or is invalid."}}}},"/v1/phone-numbers/port-in/documents":{"post":{"x-resource-group":"telephony","operationId":"uploadPhoneNumberPortInDocument","tags":["Phone Numbers"],"summary":"Upload a porting document","description":"Upload ONE porting document and get back its `documentId`.\n\n### Where the id goes\n\n- Signed LOA / carrier invoice: the id goes to `loaDocumentId` / `invoiceDocumentId`.\n- Country-specific document requirement (international ports): it becomes that requirement's `fieldValue`. Requirement documents are normalized to PDF automatically (regulators reject raw images).\n\n### Limits\n\n- PDF, JPEG, or PNG, 10MB max.\n- Uploads must be attached to an order within 30 minutes or the carrier deletes them.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The document (PDF/JPEG/PNG, 10MB max)."},"kind":{"type":"string","description":"'loa', 'invoice', or any short slug for requirement documents. Informational; used for the stored filename."}}}}}},"responses":{"200":{"description":"Document uploaded.","content":{"application/json":{"schema":{"type":"object","properties":{"documentId":{"type":"string"}}}}}},"400":{"description":"Missing file, file too large, or unsupported type"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/phone-numbers/port-in/requirements":{"get":{"x-resource-group":"telephony","operationId":"getPhoneNumberPortInRequirements","tags":["Phone Numbers"],"summary":"Country porting requirements","description":"The country-specific information a port-in needs BEYOND the LOA, invoice, and account/address details, such as an ID copy, proof of address, a tax id, or a porting code.\n\n### How to use it\n\n1. Run the portability check, which returns each number's `countryCode` and `phoneNumberType`.\n2. Call this endpoint and render the fields.\n3. Pass the collected values as the create request's `requirements`.\n\nUS/CA return an empty list.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"country","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":2},"description":"ISO country of the numbers being ported (a supported port-in country)."},{"name":"numberType","in":"query","required":false,"schema":{"type":"string","enum":["local","mobile","national","toll_free"],"default":"local"},"description":"The portability check's phoneNumberType. Requirements differ by type."}],"responses":{"200":{"description":"Requirement fields for the country/type combination.","content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string"},"numberType":{"type":"string"},"supported":{"type":"boolean","description":"false when the combination includes a step that can't be completed through the API (e.g. an in-person identity verification). Porting it needs support."},"fields":{"type":"array","items":{"type":"object","properties":{"requirementId":{"type":"string","description":"Pass back as requirements[].requirementTypeId."},"label":{"type":"string"},"kind":{"type":"string","enum":["text","date","address","file","action"],"description":"text/date take a string value; file takes a documentId from the documents endpoint; address is satisfied automatically from the end-user service address."},"description":{"type":"string"},"example":{"type":"string"},"acceptableValues":{"type":"array","items":{"type":"string"},"description":"When present, the value must be one of these."}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Country not supported for port-in"}}}},"/v1/phone-numbers/port-in/{id}/requirements":{"get":{"x-resource-group":"telephony","operationId":"getPhoneNumberPortInOrderRequirements","tags":["Phone Numbers"],"summary":"A port-in order's pending requirements","description":"The live requirements on an EXISTING porting order: which are filled,\nwhich are still pending, and which bounced on review\n(`requirement-info-exception`). Use it to fix and resubmit a rejected\ninternational port. Same field shape as the country-level requirements\nendpoint, plus per-requirement status.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Porting order ID (from the port-in list)."}],"responses":{"200":{"description":"The order's requirements with statuses.","content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string"},"requirements":{"type":"array","items":{"type":"object","properties":{"requirementId":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string","enum":["text","date","address","file","action"]},"description":{"type":"string"},"example":{"type":"string"},"acceptableValues":{"type":"array","items":{"type":"string"}},"status":{"type":"string","description":"requirement-info-pending | requirement-info-under-review | requirement-info-exception | approved"},"filled":{"type":"boolean"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Porting order not found"}}}},"/v1/phone-numbers/port-in/{id}":{"delete":{"x-resource-group":"telephony","operationId":"cancelPhoneNumberPortIn","tags":["Phone Numbers"],"summary":"Cancel a port-in","description":"Cancel an in-flight port (wrong number, staying with the old carrier).\nOnly orders that haven't ported can be cancelled; a completed port is a\nnormal number release instead. The carrier may report `cancel-pending`\nbriefly while the losing carrier acknowledges; it settles to\n`cancelled`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Porting order ID (from the port-in list)."}],"responses":{"200":{"description":"Cancel accepted (idempotent when already cancelled).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["draft","pending","foc_confirmed","ported","exception","cancelled"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Porting order not found"},"409":{"description":"Port already completed (release the number instead), or the carrier rejected the cancel (reason included)"}}}},"/v1/phone-numbers/kyc/review-packet":{"post":{"x-resource-group":"telephony","operationId":"reviewPhoneNumberKycPacket","tags":["Phone Numbers"],"summary":"Pre-review a KYC packet","description":"Advisory dry-run of a regulated-KYC packet before submitting.\n\nIt reviews the exact documents the regulator will see (referenced by the ids from POST /v1/phone-numbers/kyc/upload-document) against the declared values and address. It returns plain-language advisories for likely decline reasons (wrong document type, mismatched address, one-sided ID scans).\n\nNon-blocking: advisories are warnings, submitting anyway is always allowed, and any review failure degrades to an empty list.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["country","numberType","docs"],"properties":{"country":{"type":"string","minLength":2,"maxLength":2},"numberType":{"type":"string"},"values":{"type":"object","additionalProperties":{"type":"string"},"description":"requirementId to declared textual value."},"address":{"type":"object","additionalProperties":{"type":"string"},"description":"Declared address (street_address, locality, ...), so a mismatched proof-of-address can be flagged."},"docs":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"object","required":["requirementId","documentId"],"properties":{"requirementId":{"type":"string"},"documentId":{"type":"string","description":"Id from POST /v1/phone-numbers/kyc/upload-document."},"issuedAt":{"type":"string","format":"date","description":"Date printed on the document (YYYY-MM-DD), for slots the regulator windows such as proof of address. The pre-submit review trusts it over its own read of the PDF."}}}}}}}}},"responses":{"200":{"description":"Advisories (empty when the packet looks fine or the review was unavailable).","content":{"application/json":{"schema":{"type":"object","properties":{"advisories":{"type":"array","items":{"type":"object","properties":{"requirementId":{"type":"string"},"concern":{"type":"string","description":"One short plain-language concern about that requirement's document."}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/phone-numbers/{id}/remediate":{"get":{"x-resource-group":"telephony","operationId":"getPhoneNumberRemediation","tags":["Phone Numbers"],"summary":"Get declined requirements","description":"For a number in `regulatory_declined`, returns ONLY the requirements the reviewer flagged declined, as a form spec (same shape as the KYC form GET).\n\nThe customer fixes only those, because Telnyx supports correcting a declined requirement group and re-submitting it (no new number/group).\n\nIt falls back to the full spec if the provider exposes no per-requirement flags.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Phone number record ID."}],"responses":{"200":{"description":"The declined requirements to fix.","content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string"},"numberType":{"type":"string"},"declineReason":{"type":["string","null"]},"fields":{"type":"array","items":{"type":"object"},"description":"Same field shape as GET /v1/phone-numbers/kyc."}}}}}},"400":{"description":"Number is not awaiting remediation"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is scoped to profiles that do not include this number."},"404":{"description":"Number not found"}}},"post":{"x-resource-group":"telephony","operationId":"remediatePhoneNumber","tags":["Phone Numbers"],"summary":"Resubmit a declined number","description":"Submit corrected values/documents for the declined requirement(s). We\nPATCH them onto the SAME requirement group and re-submit it for approval;\nthe number goes `regulatory_declined` → `pending_regulatory`. No new\nnumber and no new billing. Body shape matches the KYC submit (values /\ndocuments / address). Send only the corrected fields.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"values":{"type":"object","additionalProperties":{"type":"string"}},"documents":{"type":"array","items":{"oneOf":[{"type":"object","required":["requirementId","filename","base64"],"properties":{"requirementId":{"type":"string"},"filename":{"type":"string"},"base64":{"type":"string"}}},{"type":"object","required":["requirementId","documentId"],"properties":{"requirementId":{"type":"string"},"documentId":{"type":"string"}}}]}},"address":{"type":"object","description":"Same shape as the KYC submit address."}}}}}},"responses":{"200":{"description":"Re-submitted for approval.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"resubmitted"},"phoneNumber":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}}}}}}}},"400":{"description":"Number is not awaiting remediation / nothing to remediate"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is scoped to profiles that do not include this number."},"404":{"description":"Number not found"}}}},"/v1/phone-numbers/{id}/remediate/reply":{"post":{"x-resource-group":"telephony","operationId":"replyToPhoneNumberReviewer","tags":["Phone Numbers"],"summary":"Reply to the regulatory reviewer","description":"Post a free-text reply (with optional file attachments) to the reviewer on a number awaiting remediation. Use it for asks the structured form can't express (e.g. \"is this personal or business?\").\n\nRequires text or at least one attachment. Attachments are stored by us and their links are added to the reviewer's comment thread (the carrier's number order takes no loose files).\n\n### What happens next\n\n- A reply to a comment-style ask moves the number back to \"in review\".\n- A reply on a formal decline is supplementary, and you must still resubmit the fix.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","maxLength":2000,"description":"The reply message to the reviewer."},"attachments":{"type":"array","maxItems":5,"description":"Files (PDF/JPG/PNG/WEBP, max 10 MB each) whose links are added to the reply.","items":{"type":"object","required":["filename","base64"],"properties":{"filename":{"type":"string"},"base64":{"type":"string","description":"Base64-encoded file bytes."}}}}}}}}},"responses":{"200":{"description":"Reply posted.","content":{"application/json":{"schema":{"type":"object","properties":{"posted":{"type":"boolean"},"attachments":{"type":"integer","description":"Number of attachments uploaded."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is scoped to profiles that do not include this number."},"404":{"description":"Number not found"},"502":{"description":"Couldn't deliver the reply to the reviewer; retry."}}}},"/v1/phone-numbers/{id}/remediate/respond":{"post":{"x-resource-group":"telephony","operationId":"respondToPhoneNumberReviewer","tags":["Phone Numbers"],"summary":"Respond to the regulatory reviewer (message + corrections)","description":"Send a single response to the reviewer on a number awaiting remediation: a free-text message and/or corrected requirement documents, in one call.\n\nAt least one of message, corrections, or attachments is required.\n\n- Corrections: PATCHed onto the requirement group and re-submitted (the number goes back to \"in review\").\n- Message or file attachments: posted to the reviewer's comment thread.\n- Both: your message is the thread comment and the resubmit drives the state change.\n\n### Field roles\n\n- `documents` correct requirement slots.\n- `attachments` are loose files (their links are added to your message).\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","maxLength":2000,"description":"Your message to the reviewer."},"documents":{"type":"array","description":"Corrected requirement documents, each keyed to its requirement.","items":{"type":"object","required":["requirementId"],"properties":{"requirementId":{"type":"string"},"filename":{"type":"string"},"base64":{"type":"string","description":"Base64-encoded file bytes (or supply documentId instead)."},"documentId":{"type":"string","description":"Id of a document already uploaded out-of-band."},"issuedAt":{"type":"string","format":"date","description":"Date printed on the document (YYYY-MM-DD), for slots the regulator windows such as proof of address. The pre-submit review trusts it over its own read of the PDF."}}}},"address":{"type":"object","description":"A corrected address record, keyed to its requirement."},"entityType":{"type":["string","null"],"enum":["individual","business",null]},"attachments":{"type":"array","maxItems":5,"description":"Loose files (PDF/JPG/PNG/WEBP, max 10 MB each) whose links are added to your message.","items":{"type":"object","required":["filename","base64"],"properties":{"filename":{"type":"string"},"base64":{"type":"string","description":"Base64-encoded file bytes."}}}}}}}}},"responses":{"200":{"description":"Response sent.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["resubmitted","replied"],"description":"`resubmitted` when corrections were submitted, `replied` when it was message-only."},"posted":{"type":"boolean","description":"Whether a message/attachments were posted to the reviewer."},"phoneNumber":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}}},"siblingsResubmitted":{"type":"integer","description":"Other numbers on the same registration the correction fanned out to."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is scoped to profiles that do not include this number."},"404":{"description":"Number not found"},"409":{"description":"Number's registration is held under our own carrier registration; nothing for you to correct."},"502":{"description":"Couldn't deliver your response to the reviewer; retry."}}}},"/v1/whatsapp/phone-numbers/kyc":{"get":{"x-resource-group":"telephony","operationId":"getWhatsAppNumberKycForm","deprecated":true,"tags":["WhatsApp Phone Numbers"],"summary":"Get KYC form spec","description":"Deprecated alias of `/v1/phone-numbers/kyc`; same contract. New\nintegrations should use that path.\n\nFor a Tier 3/4 country, the fields the end customer must provide (Telnyx\nregulatory requirements) before a number can be ordered: text, date,\naddress, or file (document) per requirement.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"country","in":"query","required":true,"schema":{"type":"string"}},{"name":"profileId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The KYC form spec.","content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string"},"numberType":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"requirementId":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string","enum":["text","date","address","file","action"],"description":"\"action\" = an out-of-band verification (e.g. Onfido); not filled here, fulfilled after the order via a link."},"description":{"type":["string","null"],"description":"Plain-English explanation of what to provide."},"example":{"type":["string","null"],"description":"Concrete example value."},"localTo":{"type":["string","null"],"description":"ISO country the value must be local to"},"audience":{"type":["string","null"],"enum":["business","individual",null],"description":"When set, the requirement applies ONLY to this end-user type: provide it for that type and OMIT it for the other.\n\nExample (Brazil): \"Cartão CNPJ\" is business-only; \"CPF\" and \"ID/Passport Copy\" are personal-only.\n\nSubmitting both sets makes the regulator ask whether the number is for personal or business use, which stalls the review. Pass `entityType` on POST so the server drops the inapplicable set."}}}},"reusable":{"type":["object","null"],"description":"Present when this account already has a reusable verification for the country (skip the form).\n\n- `fromPhoneNumber`/`details` mirror the first option.\n- `options` lists ALL reusable verifications (agencies hold one per end client), approved-first. Pass the chosen option's `id` as `reuseOptionId` on POST.\n- Each option's `instant` says whether it activates in minutes (group-approved) or still queues for carrier review (1-3 days).\n","properties":{"available":{"type":"boolean"},"fromPhoneNumber":{"type":"string"},"details":{"type":"array","description":"Human-readable summary of the verification on file (field labels + values, plus the address as one line). Best-effort. May be empty if the provider lookup fails.","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}}}},"options":{"type":"array","description":"One entry per distinct approved verification, newest first.","items":{"type":"object","properties":{"id":{"type":"string","description":"Opaque option id. Pass as `reuseOptionId` on POST. Stable selection key (a phone number is not unique across verifications)."},"fromPhoneNumber":{"type":"string","description":"Display only. The number this verification was submitted for. Not a selection key."},"instant":{"type":"boolean","description":"true = group-approved, a new order activates in minutes; false = documents are reused but the order still queues for carrier review (1-3 days)."},"details":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"},"documentId":{"type":"string","description":"Present on document rows: the Telnyx document id. GET /v1/whatsapp/phone-numbers/kyc/document/{documentId} streams it (auth-scoped, inline PDF)."}}}}}}}}},"pendingReview":{"type":"boolean","description":"true when this account already has a number for this country in regulatory review (status pending_regulatory).\n\nScope is the whole account across all profiles, and the country only (any number type), so it is not a per-end-client signal on a multi-tenant setup. Informational only: it never blocks a submission, and several same-country numbers may sit in review at once.\n\nFor a per-end-client view, call GET /v1/phone-numbers with `profileId` and `status=pending_regulatory`; it also lists numbers declined in the last 30 days."}}}}}},"400":{"description":"Country not available"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"x-resource-group":"telephony","operationId":"submitWhatsAppNumberKyc","deprecated":true,"tags":["WhatsApp Phone Numbers"],"summary":"Submit KYC","description":"Deprecated alias of `/v1/phone-numbers/kyc`; same contract. New integrations should use that path.\n\nSubmit the end customer's KYC (textual values, uploaded documents, address) for a Tier 3/4 country. Documents are streamed straight to the number provider and are not stored by Zernio.\n\n### What happens on submit\n\n1. Zernio builds and submits a regulatory requirement group and claims a pending_regulatory slot.\n2. The number is ordered + activated once the provider approves (asynchronous).\n\nA customer may hold several same-country numbers in review at once. A double-submit of the SAME attempt is deduped via `submissionId`.\n\n### ID-card documents\n\nCarriers commonly require BOTH sides: combine the front and back into a single file before uploading (the dashboard does this automatically). A one-sided ID is a common decline reason; fix it via POST /v1/whatsapp/phone-numbers/{id}/remediate.\n\n### Check availability first\n\nBefore submitting, call GET /v1/whatsapp/phone-numbers/availability to check the country has deliverable inventory and, for geographic-match countries, which area the address must be in. Otherwise the submission can pass review yet never be assignable a number.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","country"],"properties":{"profileId":{"type":"string"},"country":{"type":"string"},"submissionId":{"type":"string","description":"Idempotency token for this submission attempt. Omit it and every call provisions a new number.\n\n- Once the number has been ordered, a retry with the same token returns that same number instead of ordering another.\n- A submission that fails before the number is ordered releases the token, so you can correct your details and re-submit with it."},"quantity":{"type":"integer","minimum":1,"maximum":5,"default":1,"description":"Provision several same-country numbers from one submission (1-5). The single verification covers all of them; each number is billed only when it activates. Numbers that fail to order are skipped (best-effort). With `areaCode`, a quantity above that area's live stock is rejected with a 400."},"reuse":{"type":"boolean","description":"Reuse a prior approved verification for this country (skips document/field collection; places the order immediately)."},"reuseOptionId":{"type":"string","description":"Which reusable verification to use (GET reusable.options[].id). The unambiguous selection key. Omitted = the approved default. No match = 409."},"reuseFrom":{"type":"string","description":"Legacy fallback for `reuseOptionId`: the source phone number (GET reusable.options[].fromPhoneNumber). Ambiguous when a number labels two verifications, so prefer `reuseOptionId`. Omitted = the approved default. No match = 409."},"areaCode":{"type":"string","pattern":"^\\d{1,4}$","description":"Area code (NDC) the number must be in. Omit for any area.\n\nHard constraint: an empty area pool fails with 409 code AREA_CODE_UNAVAILABLE instead of ordering from another area.\n\nOptions come from GET /v1/phone-numbers/availability (areaOptions). The purchase 202 kycUrl echoes the areaCode picked at purchase time so it can be passed here."},"phoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"Exact number to order, in E.164, taken from GET /v1/whatsapp/phone-numbers/available. It is ordered as is or the request fails with 409 code phone_number_unavailable; another number is never substituted and a pre-order is never placed. Requires quantity 1 (or omitted). Omit to let the carrier pick a number in the area."},"preOrder":{"type":"boolean","description":"Pre-order a number when the area has no stock.\n\n- **With areaCode:** pre-order that area when it has no stock (listed in soldOutAreas with preOrderable true) instead of failing with AREA_CODE_UNAVAILABLE. The carrier sources a number in that area.\n- **Without areaCode:** accepts the pre-order a previous submit offered with 409 code area_pre_order_available (a geographic-match country whose address area has no stock). Resend the same body with preOrder true and the order is placed for that area.\n\nA whole pair with no stock is pre-ordered without either flag."},"endUserFirstName":{"type":"string","description":"End user's legal first name. Required when the country has an action/ID-verification (Onfido) requirement."},"endUserLastName":{"type":"string","description":"End user's legal last name. Same condition as endUserFirstName."},"values":{"type":"object","additionalProperties":{"type":"string"},"description":"requirementId → textual value"},"documents":{"type":"array","description":"One per document requirement. Each is EITHER inline base64 OR a `documentId` returned by POST /v1/whatsapp/phone-numbers/kyc/upload-document (use the upload endpoint for large files to stay under the request-size limit).","items":{"oneOf":[{"type":"object","required":["requirementId","filename","base64"],"properties":{"requirementId":{"type":"string"},"filename":{"type":"string"},"base64":{"type":"string"}}},{"type":"object","required":["requirementId","documentId"],"properties":{"requirementId":{"type":"string"},"documentId":{"type":"string","description":"Id from POST /v1/whatsapp/phone-numbers/kyc/upload-document."}}}]}},"address":{"type":"object","properties":{"requirementId":{"type":"string"},"country_code":{"type":"string"},"business_name":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"street_address":{"type":"string"},"extended_address":{"type":"string","description":"Address complement: apartment, suite, unit, or the quadra/lote used in some countries. Optional. Does not substitute for a building number on street_address."},"locality":{"type":"string"},"administrative_area":{"type":"string"},"postal_code":{"type":"string"}}}}}}}},"responses":{"200":{"description":"KYC submitted (or already submitted); number pending review.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["kyc_submitted","kyc_reused","kyc_already_submitted"]},"preOrder":{"type":"boolean","description":"True when this submission placed a pre-order instead of an order from stock. That happens when:\n\n- the country and type had nothing deliverable;\n- the picked areaCode was sold out (preOrder: true sent); or\n- the country requires the number's area to cover the registered address, that area has no stock, and the caller accepted the offer (preOrder true after a 409 area_pre_order_available). The carrier is then asked for a number in exactly that area.\n\nThe number stays `pending_regulatory` until we get it, from regular stock the moment it returns or sourced by the carrier (usually 2 to 4 weeks, never guaranteed). It is not billed until active.\n\nReleasing it (DELETE /v1/phone-numbers/{id}) cancels the pre-order. A pre-order is one number: `quantity` above 1 is rejected with 400."},"phoneNumber":{"type":"object","description":"The first/primary number, kept at the top level for backward compatibility. See `numbers` for the full set when `quantity` > 1.","properties":{"id":{"type":"string"},"status":{"type":"string"},"country":{"type":"string"}}},"numbers":{"type":"array","description":"Every number provisioned from this submission. Length equals the requested `quantity` on full success (fewer if some orders failed; best-effort). The first element mirrors `phoneNumber`.","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"phoneNumber":{"type":"string"},"country":{"type":"string"}}}}}}}}},"400":{"description":"Validation error (e.g. address not in-country, file too large)"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/BalanceRequired"},"409":{"x-summary":"Nothing was created because the requested number or area is unavailable: pick another, or resend with `preOrder` when a pre-order is offered.","description":"A conflict on the KYC order. The `code` says why:\n\n- area_pre_order_available: the country requires the number to cover the registered address and that area has no stock, but the carrier can source one. Nothing was created (see the pre-order note below).\n- area_code_unavailable: the requested areaCode (or, in a geographic-match country, the area covering the registered address) has no deliverable inventory and cannot be pre-ordered. Pick another area, or a registered address in an area with stock.\n- country_out_of_stock: the whole country and type pool has nothing deliverable and cannot be pre-ordered. Choose an area with stock or set a stock watch.\n- phone_number_unavailable (param phoneNumber): phoneNumber was sent and that exact number is no longer available (or WhatsApp cannot use it). Nothing was ordered; pick another number.\n\n**Pre-order**: details carries { areaCode, areaName, estimatedWeeks: \"2-4\", billedWhenActive: true }. Show it to the customer and, once they agree, resend the same body with preOrder true (optionally with details.areaCode as areaCode).\n\nAlso returned when reuse was requested but no prior approved verification exists for this country.\n\nWhen the only numbers the carrier lists failed WhatsApp registration recently and are held back, the message names the date the first one clears, and details.undeliverableUntil carries it as an ISO timestamp."},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/v1/whatsapp/phone-numbers/kyc/upload-document":{"post":{"x-resource-group":"telephony","operationId":"uploadWhatsAppNumberKycDocument","deprecated":true,"tags":["WhatsApp Phone Numbers"],"summary":"Upload a KYC document","description":"Deprecated alias of `/v1/phone-numbers/kyc/upload-document`; same contract. New integrations should use that path.\n\nUpload ONE document and get back its provider document id, to reference from POST /v1/whatsapp/phone-numbers/kyc via `documents[].documentId`.\n\n### Request format\n\n- Send the RAW file bytes as the request body (not base64).\n- Put the filename in the `X-Filename` header.\n- Uploading documents one-per-request keeps each request under the ~4.5MB body limit.\n\nThe document streams straight to the number provider and is not stored by Zernio.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"X-Filename","in":"header","required":true,"schema":{"type":"string"},"description":"URL-encoded original filename."}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Document uploaded.","content":{"application/json":{"schema":{"type":"object","properties":{"documentId":{"type":"string","description":"Reference this id in the KYC submit's documents[].documentId."}}}}}},"400":{"description":"Missing X-Filename, empty body, or file too large (over 20MB)."},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/whatsapp/phone-numbers/kyc/validate-address":{"post":{"x-resource-group":"telephony","operationId":"validateWhatsAppNumberKycAddress","deprecated":true,"tags":["WhatsApp Phone Numbers"],"summary":"Pre-validate KYC address","description":"Deprecated alias of `/v1/phone-numbers/kyc/validate-address`; same contract. New integrations should use that path.\n\nOptional early check for the address step of a Tier 4 (end-user identity) registration. It validates a postal address for deliverability BEFORE the full KYC submit, so it can be corrected before any documents are uploaded.\n\nThe full submit (POST /v1/whatsapp/phone-numbers/kyc) re-validates the address, so this call is purely a fast feedback path and skipping it is safe.\n\n- Only the postal address is sent (no documents, no gov-ID fields).\n- A region (`administrative_area`) is required by the validator. When it is omitted the pre-check is skipped and `{ ok: true, skipped: true }` is returned (the final submit still validates).\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["country","street_address","locality","postal_code"],"properties":{"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country code."},"street_address":{"type":"string"},"extended_address":{"type":"string","description":"Address complement: apartment, suite, unit, or the quadra/lote used in some countries. Optional. Does not substitute for a building number on street_address."},"locality":{"type":"string","description":"City / town."},"administrative_area":{"type":"string","description":"State / province / region. When omitted, the pre-check is skipped (the final submit still validates)."},"postal_code":{"type":"string"}}}}}},"responses":{"200":{"description":"Address is deliverable, or the pre-check was skipped (no region supplied).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"skipped":{"type":"boolean","description":"true when no `administrative_area` was supplied, so no pre-check ran."}}}}}},"400":{"x-summary":"The country is not offered or the address could not be verified: apply the suggested corrections from the error details when present.","description":"The country isn't offered, or the address could not be verified. When the\nprovider returned usable corrections, `details.addressSuggestions` carries\nthem per field for a one-click \"apply suggestion\" card. (Flat error\nenvelope: `error` is the human message; `code`/`param`/`details` are\ntop-level siblings.)\n","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message."},"type":{"type":"string"},"code":{"type":"string","example":"INVALID_FIELD_VALUE"},"param":{"type":"string","example":"address"},"details":{"type":"object","properties":{"addressSuggestions":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","example":"administrative_area"},"label":{"type":"string","example":"State / Province"},"value":{"type":"string","example":"Dublin"}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/whatsapp/phone-numbers/kyc/share":{"post":{"x-resource-group":"telephony","operationId":"createWhatsAppNumberKycLink","deprecated":true,"tags":["WhatsApp Phone Numbers"],"summary":"Create a hosted KYC link","description":"Deprecated alias of `/v1/phone-numbers/kyc/share`; same contract. New integrations should use that path.\n\nCreates a single-use, 7-day hosted KYC link that your end customer completes WITHOUT a Zernio login. Useful when the person who holds the ID and address is not your team.\n\nThey fill the regulated verification on a Zernio-hosted page; the number provisions under YOUR account once they submit. Only regulated (KYC) countries are valid: a country that does not require KYC returns 400.\n\n### Options\n\n- White-label the page with `branding` (your company name, logo, brand color).\n- Supply `redirect_url` to send the end customer back to your own site after a successful submit (completion params are appended; see below).\n- Listen for the `whatsapp.number.kyc_submitted` webhook to react when the form is completed.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","country"],"properties":{"profileId":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country code (must be a regulated/KYC country)."},"areaCode":{"type":"string","pattern":"^\\d{1,4}$","description":"Area code (NDC) the eventual number must be in. Hard constraint carried by the link; the end customer filling the form makes no area choice. Options come from GET /v1/phone-numbers/availability (areaOptions)."},"language":{"type":"string","enum":["en","es","pt-BR"],"description":"Language of the hosted page: its copy, the carrier requirement texts (translated once per country and cached), the pre-submit review notes and the status emails to the end customer.\n\nOmitted: the end customer's browser language, falling back to English. The end customer can also switch with `?lang=` on the page.\n"},"branding":{"type":"object","description":"Optional white-label of the hosted page the end customer sees.","properties":{"companyName":{"type":"string","maxLength":60,"description":"Your company name, shown on the hosted page."},"logoUrl":{"type":"string","format":"uri","description":"Logo shown above the form."},"brandColor":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","description":"Hex color (e.g. #1a73e8) used as a brand accent on the page."}}},"redirect_url":{"type":"string","format":"uri","description":"Where to send the end customer's browser after a successful\nsubmit. On completion Zernio appends `kyc=submitted` and\n`country=<ISO-2>` as query params. When omitted, the hosted\npage shows a built-in confirmation screen instead.\n"}}}}}},"responses":{"200":{"description":"Hosted KYC link created.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"The hosted link to send your end customer."},"token":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Country does not require KYC (not a regulated country)."},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/whatsapp/phone-numbers/{id}/profile":{"patch":{"x-resource-group":"telephony","operationId":"moveWhatsAppNumberToProfile","tags":["WhatsApp Phone Numbers"],"summary":"Move a number to another profile","description":"Move a provisioned number to a different profile.\n\nA number is not a single record. These all carry a profileId, and this endpoint moves them together:\n\n- the number itself\n- hidden telephony owner accounts (platform `phone`, plus `sms` when SMS is enabled)\n- the `whatsapp` account, once WhatsApp is connected\n\n### Why not `PATCH /v1/accounts/{accountId}`\n\nThat endpoint moves the account only and leaves the number itself pinned to its original profile, which splits the number across two profiles.\n\nConnecting a Zernio-provisioned number from any profile but its own is rejected with a `409` (`WHATSAPP_NUMBER_PINNED_TO_PROFILE`). This endpoint is how you re-home the number first, so it can then be connected from the new profile.\n\n### Notes\n\n- `id` is the number record id from `GET /v1/phone-numbers`, not an account id.\n- The destination profile may already hold other numbers.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsAppPhoneNumber id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId"],"properties":{"profileId":{"type":"string","description":"Destination profile id. Must belong to the same team."}}}}}},"responses":{"200":{"description":"Number moved, or already on that profile.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"profileId":{"type":"string","description":"The profile the number is now on."},"movedPlatforms":{"type":"array","items":{"type":"string"},"description":"Platforms whose accounts travelled with the number (phone, sms, whatsapp). Absent when the number was already on the destination profile."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"No access to the source or destination profile, or the Inbox add-on is not active."},"404":{"description":"Number not found, or the destination profile does not exist."},"409":{"description":"The number cannot move, for example because the same number is already connected on the destination profile."}}}},"/v1/whatsapp/phone-numbers/{id}/remediate":{"get":{"x-resource-group":"telephony","operationId":"getWhatsAppNumberRemediation","deprecated":true,"tags":["WhatsApp Phone Numbers"],"summary":"Get declined requirements","description":"Deprecated alias of `/v1/phone-numbers/{id}/remediate`; same contract. New integrations should use that path.\n\nFor a number in `regulatory_declined`, returns ONLY the requirements the reviewer flagged declined, as a form spec (same shape as the KYC form GET).\n\nThe customer fixes only those, because Telnyx supports correcting a declined requirement group and re-submitting it (no new number/group).\n\nFalls back to the full spec if the provider exposes no per-requirement flags.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsAppPhoneNumber id."}],"responses":{"200":{"description":"The declined requirements to fix.","content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string"},"numberType":{"type":"string"},"declineReason":{"type":["string","null"]},"fields":{"type":"array","items":{"type":"object"},"description":"Same field shape as GET /v1/whatsapp/phone-numbers/kyc."}}}}}},"400":{"description":"Number is not awaiting remediation"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is scoped to profiles that do not include this number."},"404":{"description":"Number not found"}}},"post":{"x-resource-group":"telephony","operationId":"remediateWhatsAppNumber","deprecated":true,"tags":["WhatsApp Phone Numbers"],"summary":"Resubmit a declined number","description":"Deprecated alias of `/v1/phone-numbers/{id}/remediate`; same contract. New\nintegrations should use that path.\n\nSubmit corrected values/documents for the declined requirement(s). We\nPATCH them onto the SAME requirement group and re-submit it for approval;\nthe number goes `regulatory_declined` → `pending_regulatory`. No new\nnumber and no new billing. Body shape matches the KYC submit (values /\ndocuments / address). Send only the corrected fields.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"values":{"type":"object","additionalProperties":{"type":"string"}},"documents":{"type":"array","items":{"oneOf":[{"type":"object","required":["requirementId","filename","base64"],"properties":{"requirementId":{"type":"string"},"filename":{"type":"string"},"base64":{"type":"string"}}},{"type":"object","required":["requirementId","documentId"],"properties":{"requirementId":{"type":"string"},"documentId":{"type":"string"}}}]}},"address":{"type":"object","description":"Same shape as the KYC submit address."}}}}}},"responses":{"200":{"description":"Re-submitted for approval.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"resubmitted"},"phoneNumber":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}}}}}}}},"400":{"description":"Number is not awaiting remediation / nothing to remediate"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is scoped to profiles that do not include this number."},"404":{"description":"Number not found"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/v1/phone-numbers/{id}/voice":{"post":{"x-resource-group":"telephony","operationId":"enableVoiceOnNumber","tags":["Voice"],"summary":"Enable phone calling on a number","description":"Turns on regular phone (PSTN) calling for one of your numbers and configures how inbound calls are handled.\n\nInbound calls route to `forwardTo`: your own AI voice agent (Vapi/Retell), a phone, or a SIP endpoint. A number can also be voice-enabled with no forward (outbound-only).\n\nOptional extras: voicemail, business-hours windows, an IVR menu, a caller blocklist, recording, and transcription.\n\n### Updating settings\n\nIdempotent, and doubles as the settings update: only fields present in the body are written.\n\n- Omitting `forwardTo` preserves the current destination.\n- Sending an empty string clears it.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Phone number record ID (from GET /v1/phone-numbers)."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"forwardTo":{"type":"string","description":"tel:+E164, sip:..., or wss://... destination for inbound calls. Empty string clears the forward (outbound-only); omitted preserves the current one."},"recordingEnabled":{"type":"boolean"},"transcriptionEnabled":{"type":"boolean"},"transcriptionLanguage":{"type":"string","enum":["auto","en","es"]},"voicemailEnabled":{"type":"boolean","description":"Voicemail is taken when there's no live destination. Default on."},"voicemailGreeting":{"type":"string","maxLength":1000,"description":"Custom spoken greeting; empty string restores the default."},"businessHoursEnabled":{"type":"boolean","description":"Outside the windows, inbound skips the forward and goes to voicemail. Off = 24/7."},"businessHoursTimezone":{"type":"string","maxLength":64,"description":"IANA timezone the windows are evaluated in."},"businessHours":{"type":"array","maxItems":21,"items":{"type":"object","required":["day","open","close"],"properties":{"day":{"type":"integer","minimum":0,"maximum":6,"description":"0 = Sunday."},"open":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"close":{"type":"string","pattern":"^\\d{2}:\\d{2}$"}}}},"blockedCallers":{"type":"array","maxItems":1000,"items":{"type":"string"},"description":"E.164 numbers rejected before answer. Replaces the whole list; bare 10-digit values are normalized as US numbers."},"forwardCallerId":{"type":"string","enum":["business","caller"],"description":"Caller ID on the forwarded leg: your number (`business`) or the original caller's (`caller`)."},"ivrEnabled":{"type":"boolean","description":"IVR menu (supersedes the plain forward within business hours)."},"ivrPrompt":{"type":"string","maxLength":1000},"ivrOptions":{"type":"array","maxItems":12,"items":{"type":"object","required":["digit","forwardTo"],"properties":{"digit":{"type":"string","pattern":"^[0-9*#]$"},"forwardTo":{"type":"string","description":"tel:+E164, sip:..., or wss://... destination for this digit."},"label":{"type":"string","maxLength":80}}}}}}}}},"responses":{"200":{"description":"Voice enabled; the full effective voice config is echoed back.","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"phoneNumber":{"type":"string"},"pstnForwardTo":{"type":["string","null"]},"recordingEnabled":{"type":"boolean"},"transcriptionEnabled":{"type":"boolean"},"transcriptionLanguage":{"type":"string","enum":["auto","en","es"]},"voicemailEnabled":{"type":"boolean"},"voicemailGreeting":{"type":["string","null"]},"businessHoursEnabled":{"type":"boolean"},"businessHoursTimezone":{"type":["string","null"]},"businessHours":{"type":"array","items":{"type":"object","properties":{"day":{"type":"integer"},"open":{"type":"string"},"close":{"type":"string"}}}},"blockedCallers":{"type":"array","items":{"type":"string"}},"forwardCallerId":{"type":"string","enum":["business","caller"]},"ivrEnabled":{"type":"boolean"},"ivrPrompt":{"type":["string","null"]},"ivrOptions":{"type":"array","items":{"type":"object","properties":{"digit":{"type":"string"},"forwardTo":{"type":"string"},"label":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is scoped to profiles that do not include this number."},"404":{"description":"Number not found"},"409":{"description":"This number is attached to a SIP trunk; detach it first (code invalid_resource_state)."},"422":{"description":"This number is hosted by your own carrier (brought via WhatsApp embedded signup), so calls can't be enabled on it."}}},"delete":{"x-resource-group":"telephony","operationId":"disableVoiceOnNumber","tags":["Voice"],"summary":"Disable phone calling on a number","description":"Turns off PSTN calling for the number. The stored forward destination\nand settings are preserved, so re-enabling restores the prior config.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Voice disabled.","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Always false after a successful disable."},"phoneNumber":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is scoped to profiles that do not include this number."},"404":{"description":"Number not found"}}}},"/v1/phone-numbers/stock-watches":{"post":{"x-resource-group":"telephony","operationId":"createPhoneNumberStockWatch","tags":["Phone Numbers"],"summary":"Watch an out-of-stock country","description":"Get notified the first time an out-of-stock country has deliverable numbers again: an email to the account holder plus the `phone_number.stock_available` webhook.\n\n- Stock is re-checked every 6h.\n- One watch per country and number type; a repeat request returns the existing watch (200).\n- The watch is consumed when it fires, so re-create it if you miss the stock.\n- Up to 20 watches at once.\n\n### What can be watched\n\nCountries and types marked `fulfilment: request` by GET /v1/phone-numbers/countries can also be watched. Anything with `preOrderable: true` does not need a watch: submit KYC and the carrier sources the number to order.\n\nPass `areaCode` (with `numberType`) to watch one sold-out area, for example an entry of `soldOutAreas` from GET /v1/phone-numbers/availability. Area stock is checked live on the same 6h cadence.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["country"],"properties":{"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 code of a country listed by GET /v1/phone-numbers/countries."},"numberType":{"type":"string","enum":["local","mobile","national","toll_free"],"description":"Narrow the watch to one number type. Omit to be notified when any type in the country is back."},"areaCode":{"type":"string","pattern":"^\\d{1,4}$","description":"Narrow the watch to one area code (NDC). Requires numberType."}}}}}},"responses":{"200":{"description":"A watch for this country and type already existed; returned unchanged.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PhoneNumberStockWatch"},{"type":"object","properties":{"preOrderable":{"type":"boolean","description":"See the 201 response."}}}]}}}},"201":{"description":"Watch created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PhoneNumberStockWatch"},{"type":"object","properties":{"preOrderable":{"type":"boolean","description":"True when the watched area can be bought today as a pre-order (the carrier lists nothing there and the type is a document tier): submit KYC with `areaCode` and `preOrder: true` instead of waiting, usually 2 to 4 weeks, nothing billed until active. The watch is armed either way."}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"x-summary":"The country or area is already in stock, so buy instead, or you reached the 20-watch limit.","description":"The country (or the watched area) is in stock right now (buy instead of watching), or the 20-watch limit is reached (code invalid_resource_state)."}}},"get":{"x-resource-group":"telephony","operationId":"listPhoneNumberStockWatches","tags":["Phone Numbers"],"summary":"List stock watches","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The caller's active watches, oldest first.","content":{"application/json":{"schema":{"type":"object","properties":{"watches":{"type":"array","items":{"$ref":"#/components/schemas/PhoneNumberStockWatch"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/phone-numbers/stock-watches/{id}":{"delete":{"x-resource-group":"telephony","operationId":"deletePhoneNumberStockWatch","tags":["Phone Numbers"],"summary":"Stop watching a country","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Watch deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Stock watch not found (code stock_watch_not_found)."}}}},"/v1/phone-numbers/sip-trunks":{"post":{"x-resource-group":"telephony","operationId":"createSipTrunk","tags":["Voice"],"summary":"Create a SIP trunk","description":"Creates a SIP trunk an external voice platform (Retell, ElevenLabs,\nVapi, or any SIP endpoint) can import your Zernio numbers into. The\ntrunk carries both directions: inbound calls on attached numbers are\ndelivered to `sipHost`, and the platform originates outbound calls\nthrough `termination.uri` with the digest credentials.\n\nThe `digestPassword` is returned only by this call (and by\nrotate-credentials); store it immediately. Attach any number of numbers\nto a trunk. Several trunks may point at the same host. Each carries its\nown credentials and spend cap, so separate destinations (e.g.\nan agency's clients) stay isolated.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["label","sipHost"],"properties":{"label":{"type":"string","maxLength":80,"description":"Display name for the trunk."},"sipHost":{"type":"string","description":"Fully-qualified hostname inbound calls are delivered to (e.g. sip.rtc.elevenlabs.io, sip.retellai.com)."},"sipPort":{"type":"integer","minimum":1,"maximum":65535,"description":"Defaults to 5061 for tls, 5060 otherwise."},"transport":{"type":"string","enum":["tls","tcp","udp"],"description":"Signaling transport toward sipHost. Default tls (with SRTP media)."}}}}}},"responses":{"201":{"x-summary":"The trunk was created: save the digest password from this response because it is shown only here and on rotate.","description":"Trunk created. The digest password is shown only here and on rotate.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"sipHost":{"type":"string"},"sipPort":{"type":"integer"},"transport":{"type":"string","enum":["tls","tcp","udp"]},"termination":{"type":"object","properties":{"uri":{"type":"string","description":"Telnyx termination host the platform dials for outbound (sip.telnyx.com)."},"username":{"type":"string","description":"SIP digest username."}}},"numbersAttached":{"type":"integer"},"createdAt":{"type":["string","null"],"format":"date-time"},"digestPassword":{"type":"string","description":"SIP digest password, shown only in this response."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/BalanceRequired"},"403":{"x-summary":"The team is on legacy billing that cannot invoice trunk call costs: move to usage-based billing to use SIP trunking.","description":"The team is on legacy (non-usage-based) billing, which cannot invoice trunk call costs (code feature_not_available). Move to usage-based billing to use SIP trunking."},"409":{"description":"The team trunk limit was reached (code invalid_resource_state)."},"422":{"x-summary":"The host cannot be a trunk destination, for example a Zernio or carrier host: use a different host.","description":"The host cannot be used as a trunk destination (e.g. a Zernio or carrier host)."}}},"get":{"x-resource-group":"telephony","operationId":"listSipTrunks","tags":["Voice"],"summary":"List SIP trunks","security":[{"bearerAuth":[]}],"responses":{"200":{"x-summary":"The team's SIP trunks are returned, and passwords are never included.","description":"The team's trunks. Passwords are never included.","content":{"application/json":{"schema":{"type":"object","properties":{"trunks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"sipHost":{"type":"string"},"sipPort":{"type":"integer"},"transport":{"type":"string","enum":["tls","tcp","udp"]},"termination":{"type":"object","properties":{"uri":{"type":"string"},"username":{"type":"string"}}},"numbersAttached":{"type":"integer"},"createdAt":{"type":["string","null"],"format":"date-time"}}}},"enabled":{"type":"boolean","description":"Whether this team can create SIP trunks. Managing existing trunks always works."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/phone-numbers/sip-trunks/{id}":{"get":{"x-resource-group":"telephony","operationId":"getSipTrunk","tags":["Voice"],"summary":"Get a SIP trunk","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Trunk detail, including the attached numbers.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"sipHost":{"type":"string"},"sipPort":{"type":"integer"},"transport":{"type":"string","enum":["tls","tcp","udp"]},"termination":{"type":"object","properties":{"uri":{"type":"string"},"username":{"type":"string"}}},"numbersAttached":{"type":"integer"},"createdAt":{"type":["string","null"],"format":"date-time"},"numbers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Phone number record ID."},"phoneNumber":{"type":"string"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"SIP trunk not found"}}},"delete":{"x-resource-group":"telephony","operationId":"deleteSipTrunk","tags":["Voice"],"summary":"Delete a SIP trunk","description":"Tears down the trunk and its carrier-side objects. Refused while any\nnumber is still attached: detach them first.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Trunk deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"SIP trunk not found"},"409":{"description":"Numbers are still attached to this trunk (code invalid_resource_state)."}}}},"/v1/phone-numbers/sip-trunks/{id}/rotate-credentials":{"post":{"x-resource-group":"telephony","operationId":"rotateSipTrunkCredentials","tags":["Voice"],"summary":"Rotate a SIP trunk's password","description":"Mints a new digest password on the trunk. The old password stops\nworking immediately, so update the destination platform right away.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"x-summary":"New credentials were issued: save the password now because it is shown only in this response.","description":"New credentials. The password is shown only here.","content":{"application/json":{"schema":{"type":"object","properties":{"termination":{"type":"object","properties":{"uri":{"type":"string","description":"Telnyx termination host the platform dials for outbound (sip.telnyx.com)."},"username":{"type":"string","description":"SIP digest username."}}},"digestPassword":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"SIP trunk not found"}}}},"/v1/phone-numbers/{id}/sip-trunk":{"post":{"x-resource-group":"telephony","operationId":"attachNumberToSipTrunk","tags":["Voice"],"summary":"Attach a number to a SIP trunk","description":"Routes the number's calls to the trunk. The external platform receives its inbound directly and can present it as outbound caller ID.\n\nWhile attached, Zernio-side voice features are off for this number: call forwarding, IVR, voicemail, recording, the softphone, and WhatsApp calling. So the number must have Calls and WhatsApp calling disabled before attaching.\n\nSMS and WhatsApp messaging are unaffected.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Phone number record ID (from GET /v1/phone-numbers)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["trunkId"],"properties":{"trunkId":{"type":"string","description":"SIP trunk ID (from POST /v1/phone-numbers/sip-trunks)."}}}}}},"responses":{"200":{"description":"Number attached (idempotent for the same trunk).","content":{"application/json":{"schema":{"type":"object","properties":{"attached":{"type":"boolean"},"phoneNumber":{"type":"string"},"trunkId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/BalanceRequired"},"403":{"x-summary":"The team is on legacy billing or the API key's profiles exclude this number: move to usage-based billing or use another key.","description":"The team is on legacy (non-usage-based) billing, which cannot invoice trunk call costs (code feature_not_available). Move to usage-based billing to use SIP trunking. Also returned when the API key is scoped to profiles that do not include this number."},"404":{"description":"Number or trunk not found"},"409":{"x-summary":"The number is not in a state that allows trunk attachment: resolve its calling, WhatsApp, status or trunk conflict first.","description":"The number still has Calls or WhatsApp calling enabled, is mid WhatsApp verification, is not active, or is attached to another trunk (code invalid_resource_state)."},"422":{"description":"This number is hosted by your own carrier (brought via WhatsApp embedded signup), so it cannot be trunked."}}},"delete":{"x-resource-group":"telephony","operationId":"detachNumberFromSipTrunk","tags":["Voice"],"summary":"Detach a number from its SIP trunk","description":"Returns the number's calls to Zernio routing. Idempotent when the\nnumber is not attached to any trunk.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Number detached.","content":{"application/json":{"schema":{"type":"object","properties":{"attached":{"type":"boolean","description":"Always false after a successful detach."},"phoneNumber":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is scoped to profiles that do not include this number."},"404":{"description":"Number not found"}}}},"/v1/phone-numbers/{id}/sms":{"post":{"x-resource-group":"telephony","operationId":"enableSmsOnNumber","tags":["SMS"],"summary":"Enable SMS on a number","description":"Turns on SMS for one of your numbers. Idempotent: re-running re-attempts any carrier-side setup that failed.\n\n### Carrier capability check\n\nThe number's real carrier capability is checked first:\n\n- `smsCapable: false`: the number type can't do SMS at all.\n- `notReady: true`: the number is still provisioning at the carrier; try again once provisioning finishes.\n\n### US registration\n\nUS numbers additionally need a carrier registration before messages deliver. The response tells you which path applies:\n\n- `alreadyRegistered: true`: a prior registration still covers this number; SMS was reactivated.\n- `reusable` set: you have an approved registration this number can join in one click via `POST /v1/phone-numbers/{id}/sms/reuse-registration` (no new brand/campaign, no extra carrier fee).\n- `needsRegistration: true` and no `reusable`: start one via `POST /v1/sms/registrations`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Phone number record ID (from GET /v1/phone-numbers)."}],"responses":{"200":{"x-summary":"Check `enabled`: false means the number cannot do SMS or is not ready yet.","description":"Result. Check `enabled`: a 200 with `enabled: false` means the number can't do SMS (`smsCapable: false`) or isn't ready yet (`notReady: true`).","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"id":{"type":"string","description":"The SMS account ID (present when enabled)."},"phoneNumber":{"type":"string"},"isActive":{"type":"boolean","description":"False for US numbers until their registration is approved."},"country":{"type":"string"},"smsCapable":{"type":["boolean","null"],"description":"Null when capability can't be read yet (still provisioning)."},"mmsCapable":{"type":"boolean"},"domesticOnly":{"type":"boolean"},"notReady":{"type":"boolean","description":"Number is still provisioning at the carrier; retry shortly."},"needsRegistration":{"type":"boolean","description":"US only; a carrier registration is required before delivery."},"alreadyRegistered":{"type":"boolean","description":"A prior non-rejected registration already covers this number; no re-submit needed."},"registrationStatus":{"type":["string","null"],"enum":["pending","approved","rejected",null]},"reusable":{"type":["object","null"],"description":"Present when an existing approved registration can cover this number via /sms/reuse-registration.","properties":{"registrationId":{"type":"string"},"status":{"type":"string"}}},"message":{"type":"string","description":"Human-readable explanation when `enabled` is false."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is scoped to profiles that do not include this number."},"404":{"description":"Number not found"},"422":{"description":"This number is hosted by your own carrier (brought via WhatsApp embedded signup), so SMS can't be enabled on it."}}},"delete":{"x-resource-group":"telephony","operationId":"disableSmsOnNumber","tags":["SMS"],"summary":"Disable SMS on a number","description":"Turns off SMS for the number (deactivates its SMS account). The carrier\nregistration is untouched, so re-enabling later reactivates it,\nwith no re-registration.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SMS disabled.","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Always false after a successful disable."},"phoneNumber":{"type":"string"},"disabled":{"type":"boolean","description":"False when SMS was already off. Legacy field; prefer `enabled`."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is scoped to profiles that do not include this number."},"404":{"description":"Number not found"}}}},"/v1/phone-numbers/{id}/sms/reuse-registration":{"post":{"x-resource-group":"telephony","operationId":"reuseSmsRegistrationForNumber","tags":["SMS"],"summary":"Add number to SMS registration","description":"Attaches this number to your existing approved 10DLC campaign instead\nof running a fresh registration: the number inherits the campaign's\napproval (no new brand or campaign, no extra carrier fee). Enable SMS\non the number first (`POST /v1/phone-numbers/{id}/sms`; its response\ntells you whether a reusable registration exists).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Number added to the existing registration.","content":{"application/json":{"schema":{"type":"object","properties":{"registrationId":{"type":"string"},"status":{"type":"string","enum":["pending","approved","rejected","requested","changes_requested","deactivated"],"description":"requested/changes_requested = pre-submission review states; customers see them as pending / needs changes."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is scoped to profiles that do not include this number."},"404":{"description":"Number not found"},"409":{"description":"No existing SMS registration to reuse for this number"}}}},"/v1/phone-numbers/{id}/whatsapp/request-code":{"post":{"x-resource-group":"telephony","operationId":"requestPhoneNumberWhatsAppCode","tags":["Phone Numbers"],"summary":"Request the WhatsApp verification code for a number","description":"Starts (or restarts) WhatsApp verification of a Zernio-hosted number. Used to connect WhatsApp on a number bought for calls or SMS.\n\nZernio adds the number to Meta's pre-verified pool when needed and asks Meta to send the verification code, which Zernio captures on the number itself.\n\n`/v1/whatsapp/phone-numbers/{id}/request-code` is a deprecated alias with the same contract.\n\n### When Meta refuses the number (Meta error 136021)\n\n- A number that is already live (`active` or `suspended`) is left untouched and keeps working for calls and SMS. The call answers 409 `number_not_whatsapp_eligible`; buy a new number with WhatsApp enabled instead.\n- A number that was never live (still verifying) is replaced at no extra cost with a WhatsApp-eligible number on the same record, answered as 200 with `replaced: true`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Phone number record ID (from GET /v1/phone-numbers)."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["SMS","VOICE"],"description":"Delivery method for the code. Omit to let Zernio pick (SMS when the number can receive it, else VOICE)."}}}}}},"responses":{"200":{"description":"Code requested, or the number was already verified, or a never-live number was replaced.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"method":{"type":"string","enum":["SMS","VOICE"]},"alreadyVerified":{"type":"boolean","description":"Meta already reports the number as verified. No code is sent and the number is activated."},"replaced":{"type":"boolean","description":"Meta refused the original number, which had never been live, so it was replaced on the same record."},"newPhoneNumber":{"type":"string","description":"The replacement number, present when `replaced` is true."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is scoped to profiles that do not include this number."},"404":{"$ref":"#/components/responses/NotFound"},"409":{"x-summary":"The number cannot be verified for WhatsApp right now, for example because Meta disallows it: buy a new number for WhatsApp.","description":"The number cannot be verified for WhatsApp right now. `code` says why:\n\n- `number_not_whatsapp_eligible`: Meta does not allow this already-live number on WhatsApp. It keeps working for calls and SMS and is not replaced. Buy a new number for WhatsApp.\n- `whatsapp_number_in_use`: Meta reports the number is registered to another WhatsApp account.\n- `META_INVALID_NUMBER`: Meta refused a never-live number and no replacement could be sourced.\n- `PENDING_REGULATORY`: the number is still in carrier regulatory review.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"x-summary":"Meta paused verification for this number: retry after the time in `retryAt`.","description":"Meta paused verification for this number. `retryAt` says when it lifts."},"503":{"description":"The number is not ready for verification yet, retry shortly."}}}},"/v1/phone-numbers/{id}/whatsapp/calling":{"get":{"x-resource-group":"telephony","operationId":"getWhatsAppCalling","tags":["WhatsApp Calling"],"summary":"Get calling config for a number","description":"The WhatsApp Business Calling configuration of this number, keyed the same way as the POST/PATCH/DELETE below (full read-write on one sub-resource).\n\nEncrypted secrets are never returned; only a boolean saying whether a SIP password is stored.\n\nThe account-scoped read (`GET /v1/whatsapp/calling?accountId=`) remains for callers that only know the account id. It additionally carries account-level extras (billing eligibility, current-period spend).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Phone number record ID (from GET /v1/phone-numbers)."}],"responses":{"200":{"description":"Calling config","content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumber":{"type":"string"},"callingEnabled":{"type":"boolean"},"callDeepLink":{"type":["string","null"],"description":"Public calling deep link (https://wa.me/call/<number>). Null while calling is disabled."},"forwardTo":{"type":["string","null"],"description":"tel:+E164 / sip:... / wss://... destination"},"recordingEnabled":{"type":"boolean"},"sipAuthUsername":{"type":["string","null"]},"sipAuthPasswordConfigured":{"type":"boolean","description":"True when a SIP digest password is stored. The plaintext is never returned."},"callIconCountries":{"type":["array","null"],"items":{"type":"string","minLength":2,"maxLength":2}},"outboundDisabled":{"type":"boolean","description":"True when the number's country blocks business-initiated (outbound) WhatsApp calling; inbound still works."},"callerIdMode":{"type":"string","enum":["business","platform"],"description":"Caller ID the forward-leg callee sees on tel: forwards. business = this WhatsApp number; platform = a Zernio number (used when the number was brought by the customer and its caller ID is not verified for PSTN origination)."},"callerIdVerified":{"type":"boolean","description":"True once the number completed caller-ID verification, making tel: forwards display the business number itself."},"maxCallDurationSeconds":{"type":["integer","null"],"description":"Hard cap (seconds) on forwarded calls; null = no cap."},"forwardCallerId":{"type":"string","enum":["business","caller"]}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is scoped to profiles that do not include this number."},"404":{"description":"Number not found"}}},"post":{"x-resource-group":"telephony","operationId":"enableWhatsAppCalling","tags":["WhatsApp Calling"],"summary":"Enable calling on a number","description":"Enable WhatsApp Business Calling on a connected number. Configures\nMeta calling.status=ENABLED with our Telnyx SIP endpoint, fetches and\nstores the Meta-issued SIP password (encrypted), and snapshots the\ncustomer's forward-to destination.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Phone number record ID (from GET /v1/phone-numbers)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","forwardTo"],"properties":{"accountId":{"type":"string"},"forwardTo":{"type":"string","description":"tel:+E164 / sip:... / wss://... destination"},"sipAuthUsername":{"type":"string"},"sipAuthPassword":{"type":"string","description":"Stored encrypted, never returned by any endpoint."},"recordingEnabled":{"type":"boolean","default":false},"callIconCountries":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2}},"maxCallDurationSeconds":{"type":"integer","minimum":30,"maximum":14400,"description":"Hard cap (seconds) on a forwarded call; the carrier hangs up both legs when it fires. Safety valve against dead-air billing when a destination hangs up but the signal is lost."},"forwardCallerId":{"type":"string","enum":["business","caller"],"default":"business","description":"Caller ID presented to the forward destination. caller = the WhatsApp user's number (sip: destinations only; ignored on tel: forwards). Fixes AI-agent trunks that reject seeing the business number call itself."}}}}}},"responses":{"200":{"description":"Calling enabled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"callingEnabled":{"type":"boolean"},"sipHostname":{"type":"string"},"forwardTo":{"type":"string"},"callerIdMode":{"type":"string","enum":["business","platform"],"description":"Caller ID the forward-leg callee sees on tel: forwards. business = this WhatsApp number; platform = a Zernio number (customer-brought number without verified caller ID)."}}}}}},"400":{"x-summary":"The request is invalid, or Meta refused to enable calling, for example for a number below the required messaging tier: fix it.","description":"Invalid request (including forwardTo set to the number itself), or Meta refused enablement (platform_api_error with platformError.code 138015, for example a production number below the 2,000-recipient messaging tier; Meta public test numbers and Sandbox accounts are exempt)"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Phone number not found"},"409":{"description":"This number is attached to a SIP trunk; detach it first (code invalid_resource_state)."},"422":{"description":"Not eligible to enable calling: not on usage-based billing."}}},"patch":{"x-resource-group":"telephony","operationId":"updateWhatsAppCalling","tags":["WhatsApp Calling"],"summary":"Update calling config","description":"Update fields on an already-enabled number. Only fields present in\nthe body are written; `undefined` leaves the stored value alone,\nexplicit `null` clears a nullable field. No Meta side effect, this\nonly changes local routing state consumed by the Telnyx webhook\nhandler.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string"},"forwardTo":{"type":"string"},"sipAuthUsername":{"type":["string","null"]},"sipAuthPassword":{"type":["string","null"]},"recordingEnabled":{"type":"boolean"},"callIconCountries":{"type":["array","null"],"items":{"type":"string","minLength":2,"maxLength":2}},"maxCallDurationSeconds":{"type":["integer","null"],"minimum":30,"maximum":14400,"description":"Hard cap (seconds) on forwarded calls; null clears the cap."},"forwardCallerId":{"type":"string","enum":["business","caller"],"description":"caller = present the WhatsApp user's number to the forward destination (sip: only)."}}}}}},"responses":{"200":{"description":"Updated"},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Phone number not found"},"422":{"description":"Calling must be enabled before settings can be updated"}}},"delete":{"x-resource-group":"telephony","operationId":"disableWhatsAppCalling","tags":["WhatsApp Calling"],"summary":"Disable calling on a number","description":"Disable calling. Sends calling.status=DISABLED to Meta (best-effort)\nand flips the local `callingEnabled` flag off. forwardTo and SIP\ncreds are preserved so a re-enable does not lose the destination.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Disabled"},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Phone number not found"}}}},"/v1/phone-numbers/{id}/whatsapp/caller-id-verification":{"post":{"x-resource-group":"telephony","operationId":"startWhatsAppCallerIdVerification","tags":["WhatsApp Calling"],"summary":"Start caller-ID verification for a customer-brought number","description":"Sends a one-time code to a customer-brought (BYO) WhatsApp number by SMS or voice call, to verify it as caller ID. Re-POST to resend.\n\nBYO numbers cannot present themselves as caller ID on `tel:` call forwards until verified (carrier anti-spoofing). Until then forwarded calls show a Zernio number (`callerIdMode: platform` on the calling config).\n\nZernio-purchased numbers never need this and get a 400.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Phone number record ID (from GET /v1/phone-numbers)."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["sms","call"],"default":"sms"}}}}}},"responses":{"200":{"description":"Code sent (or the number was already verified)","content":{"application/json":{"schema":{"type":"object","properties":{"verified":{"type":"boolean"},"codeSent":{"type":"boolean"},"method":{"type":"string","enum":["sms","call"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is scoped to profiles that do not include this number."},"404":{"description":"Number not found"},"429":{"description":"Too many verification attempts for this number; wait before retrying"}}}},"/v1/phone-numbers/{id}/whatsapp/caller-id-verification/verify":{"post":{"x-resource-group":"telephony","operationId":"verifyWhatsAppCallerId","tags":["WhatsApp Calling"],"summary":"Confirm the caller-ID verification code","description":"Submits the one-time code the number received. On success, `tel:`\ncall forwards present the business number itself as caller ID\n(`callerIdMode: business`).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Phone number record ID (from GET /v1/phone-numbers)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","minLength":4,"maxLength":10}}}}}},"responses":{"200":{"description":"Verified","content":{"application/json":{"schema":{"type":"object","properties":{"verified":{"type":"boolean"}}}}}},"400":{"description":"Invalid or expired code, or malformed request"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is scoped to profiles that do not include this number."},"404":{"description":"Number not found"},"429":{"description":"Attempt lockout from the carrier; wait a few minutes, then request a fresh code"}}}},"/v1/whatsapp/phone-numbers/{phoneNumberId}":{"get":{"x-resource-group":"telephony","operationId":"getWhatsAppPhoneNumber","deprecated":true,"tags":["WhatsApp Phone Numbers"],"summary":"Get phone number","description":"Deprecated alias of `/v1/phone-numbers/{id}`; same contract. New integrations should use that path.\n\nRetrieve the current status of a purchased phone number. Poll this to track:\n\n- Meta pre-verification (US sync path)\n- for regulated (Tier 3/4) numbers, the async lifecycle: pending_regulatory → active (or regulatory_declined)\n\nWhen a regulated number has an Onfido ID step, `onfidoVerificationUrl` appears here once the order is placed. Forward it to the end user.\n\nOr subscribe to the whatsapp.number.* webhooks instead of polling.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"phoneNumberId","in":"path","required":true,"description":"Phone number record ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Phone number retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumber":{"type":"object","properties":{"id":{"type":"string"},"phoneNumber":{"type":"string"},"status":{"type":"string","enum":["pending_payment","pending_regulatory","regulatory_declined","provisioning","verifying","active","suspended","releasing","released"]},"country":{"type":"string"},"metaPreverifiedId":{"type":"string"},"metaVerificationStatus":{"type":"string"},"onfidoVerificationUrl":{"type":["string","null"],"description":"For a regulated number with an Onfido ID step: the link to forward to the end user. Appears once the order is placed; null otherwise."},"endUserFirstName":{"type":["string","null"]},"endUserLastName":{"type":["string","null"]},"regulatoryDeclineReason":{"type":["string","null"],"description":"Reviewer rejection reason when status is regulatory_declined."},"provisionedAt":{"type":"string","format":"date-time"},"sipTrunkId":{"type":["string","null"],"description":"SIP trunk the number is attached to; null when not trunked. While attached, enabling Calls or WhatsApp calling, requesting WhatsApp verification, and releasing the number all return 409."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key is scoped to profiles that do not include this number."},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"x-resource-group":"telephony","operationId":"releaseWhatsAppPhoneNumber","deprecated":true,"tags":["WhatsApp Phone Numbers"],"summary":"Release phone number","description":"Deprecated alias of `/v1/phone-numbers/{id}`; same contract. New\nintegrations should use that path.\n\nRelease a purchased phone number. This will:\n1. Disconnect any linked WhatsApp account\n2. Decrement the Stripe subscription quantity (or cancel if last number)\n3. Release the number from Telnyx\n4. Mark the number as released\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"phoneNumberId","in":"path","required":true,"description":"Phone number record ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Phone number released successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"phoneNumber":{"type":"object","properties":{"id":{"type":"string"},"phoneNumber":{"type":"string"},"status":{"type":"string","description":"\"released\""},"releasedAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Phone number is already released or being released"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"x-summary":"The number is attached to a SIP trunk or changed state during cancellation: detach it or check its state, then retry.","description":"The number is attached to a SIP trunk (detach it first), or it changed state while a pending order was being cancelled (code invalid_resource_state)."},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/v1/whatsapp/sandbox/sessions":{"get":{"x-resource-group":"messages","operationId":"listWhatsAppSandboxSessions","tags":["WhatsApp Sandbox"],"summary":"List your sandbox sessions","description":"Returns all of the authenticated user's non-expired sandbox sessions\n(pending + active) plus the sandbox phone number. In practice there\nis at most one session per user since the sandbox is one-phone-per-user;\nthe array shape is preserved for forward compatibility.\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Sessions retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"sessions":{"type":"array","items":{"$ref":"#/components/schemas/WhatsAppSandboxSession"}},"sandboxNumber":{"type":["string","null"],"description":"The shared sandbox phone number in E.164 form.","example":"+12029087457"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"}}},"post":{"x-resource-group":"messages","operationId":"createWhatsAppSandboxSession","tags":["WhatsApp Sandbox"],"summary":"Start a sandbox activation","description":"Creates (or refreshes) a pending sandbox session for the given phone and\nimmediately fires the verified sandbox template from the shared sandbox\nnumber to that phone. The session activates when the phone owner replies\nto that WhatsApp message: the reply itself is proof of ownership.\n\nOne phone per user: if the caller already has a non-expired session for\na DIFFERENT phone, the request is rejected with `invalid_field_value`\n(the message names the existing phone so it can be revoked first).\nRe-creating a session for the SAME phone is idempotent and refreshes\nthe verification template.\n\nIf Meta rejects the template send (not a WhatsApp number, paused WABA,\ntoken issue), the pending row is rolled back and the Meta error message\nis returned in `error` so the caller knows why.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","description":"Recipient phone in international format. Digits, spaces, dashes and a leading `+` are all accepted; the server normalizes to E.164 digits-only.","example":"+34688246216"}}}}}},"responses":{"200":{"description":"Session created or refreshed; verification template sent","content":{"application/json":{"schema":{"type":"object","properties":{"session":{"$ref":"#/components/schemas/WhatsAppSandboxSession"},"sandboxNumber":{"type":"string","example":"+12029087457"}}}}}},"400":{"x-summary":"The sandbox session request was rejected, for example by a bad phone format or a Meta template refusal: send a valid number.","description":"Returned when (a) phone format is invalid, (b) phone equals the sandbox\nnumber itself, (c) the user already has a session for a different phone,\nor (d) Meta rejected the template send. The `error` field contains the\nspecific reason; `param` is set when a field is at fault.\n"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"}}}},"/v1/whatsapp/sandbox/sessions/{sessionId}":{"delete":{"x-resource-group":"messages","operationId":"deleteWhatsAppSandboxSession","tags":["WhatsApp Sandbox"],"summary":"Revoke a sandbox session","description":"Hard-deletes the session. The user loses the ability to send to that\nphone via the sandbox until they re-activate it. Existing conversations\nand messages already exchanged with that phone are untouched.\nRevocation only blocks FUTURE sends.\n\nSessions belonging to other users cannot be revoked; the response is\nthe same 400 as \"session not found\" so existence isn't leaked.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session id returned by POST /v1/whatsapp/sandbox/sessions.","schema":{"type":"string"}}],"responses":{"200":{"description":"Session revoked","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"description":"Invalid or unknown session id"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Inbox addon required"}}}},"/v1/whatsapp/wa-groups":{"get":{"x-resource-group":"messages","operationId":"listWhatsAppGroupChats","tags":["WhatsApp"],"summary":"List active groups","description":"List active WhatsApp group chats for a business phone number.\nThese are actual WhatsApp group conversations on the platform.\n\nNot available on [Coexistence](/platforms/whatsapp/connect#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":1024},"description":"Max groups to return"},{"name":"after","in":"query","schema":{"type":"string"},"description":"Pagination cursor"}],"responses":{"200":{"description":"List of active groups","content":{"application/json":{"schema":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Group ID"},"subject":{"type":"string","description":"Group name"},"createdAt":{"type":"string","description":"Group creation timestamp"}}}},"paging":{"type":"object","properties":{"cursors":{"type":"object","properties":{"after":{"type":"string"},"before":{"type":"string"}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"x-resource-group":"messages","operationId":"createWhatsAppGroupChat","tags":["WhatsApp"],"summary":"Create group","description":"Create a new WhatsApp group chat. Returns the group ID and optionally an invite link.\n\nNot available on [Coexistence](/platforms/whatsapp/connect#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","subject"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"},"subject":{"type":"string","maxLength":128,"description":"Group name (max 128 characters)"},"description":{"type":"string","maxLength":2048,"description":"Group description (max 2048 characters)"},"joinApprovalMode":{"type":"string","enum":["approval_required","auto_approve"],"description":"Whether users need approval to join via invite link"}}}}}},"responses":{"201":{"description":"Group created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"group":{"type":"object","properties":{"groupId":{"type":"string"},"inviteLink":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/whatsapp/wa-groups/{groupId}":{"get":{"x-resource-group":"messages","operationId":"getWhatsAppGroupChat","tags":["WhatsApp"],"summary":"Get group info","description":"Retrieve metadata about a WhatsApp group including subject, description,\nparticipants, and settings.\n\nNot available on [Coexistence](/platforms/whatsapp/connect#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"groupId","in":"path","required":true,"schema":{"type":"string"},"description":"Group ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"}],"responses":{"200":{"description":"Group info","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"group":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string"},"description":{"type":"string"},"joinApprovalMode":{"type":"string"},"participants":{"type":"array","items":{"type":"object","properties":{"user":{"type":"string","description":"Phone number"},"admin":{"type":"string"}}}},"participantCount":{"type":"integer"},"createdAt":{"type":"integer","description":"UNIX timestamp"},"isSuspended":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"x-resource-group":"messages","operationId":"updateWhatsAppGroupChat","tags":["WhatsApp"],"summary":"Update group settings","description":"Update the subject, description, or join approval mode of a WhatsApp group.\n\nNot available on [Coexistence](/platforms/whatsapp/connect#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"groupId","in":"path","required":true,"schema":{"type":"string"},"description":"Group ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string","maxLength":128},"description":{"type":"string","maxLength":2048},"joinApprovalMode":{"type":"string","enum":["approval_required","auto_approve"]}}}}}},"responses":{"200":{"description":"Group updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"x-resource-group":"messages","operationId":"deleteWhatsAppGroupChat","tags":["WhatsApp"],"summary":"Delete group","description":"Delete a WhatsApp group and remove all participants.\n\nNot available on [Coexistence](/platforms/whatsapp/connect#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"groupId","in":"path","required":true,"schema":{"type":"string"},"description":"Group ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"}],"responses":{"200":{"description":"Group deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/whatsapp/wa-groups/{groupId}/participants":{"post":{"x-resource-group":"messages","operationId":"addWhatsAppGroupParticipants","tags":["WhatsApp"],"summary":"Add participants","description":"Add participants to a WhatsApp group. Maximum 8 participants per request. A group holds at most 8 participants in total (a Meta limit), so later requests cannot grow a group past 8. Meta documents groups as invite-only, so people normally join through the group's invite link.\n\nNot available on [Coexistence](/platforms/whatsapp/connect#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"groupId","in":"path","required":true,"schema":{"type":"string"},"description":"Group ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phoneNumbers"],"properties":{"phoneNumbers":{"type":"array","maxItems":8,"items":{"type":"string"},"description":"Phone numbers in E.164 format (max 8)"}}}}}},"responses":{"200":{"description":"Participants added","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"delete":{"x-resource-group":"messages","operationId":"removeWhatsAppGroupParticipants","tags":["WhatsApp"],"summary":"Remove participants","description":"Remove participants from a WhatsApp group.\n\nNot available on [Coexistence](/platforms/whatsapp/connect#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"groupId","in":"path","required":true,"schema":{"type":"string"},"description":"Group ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phoneNumbers"],"properties":{"phoneNumbers":{"type":"array","items":{"type":"string"},"description":"Phone numbers to remove"}}}}}},"responses":{"200":{"description":"Participants removed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/whatsapp/wa-groups/{groupId}/invite-link":{"post":{"x-resource-group":"messages","operationId":"createWhatsAppGroupInviteLink","tags":["WhatsApp"],"summary":"Create invite link","description":"Create a new invite link for a WhatsApp group. The previous link is revoked.\n\nNot available on [Coexistence](/platforms/whatsapp/connect#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"groupId","in":"path","required":true,"schema":{"type":"string"},"description":"Group ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"}],"responses":{"200":{"description":"Invite link created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"inviteLink":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/whatsapp/wa-groups/{groupId}/join-requests":{"get":{"x-resource-group":"messages","operationId":"listWhatsAppGroupJoinRequests","tags":["WhatsApp"],"summary":"List join requests","description":"List pending join requests for a WhatsApp group (only for groups with approval_required mode).\n\nNot available on [Coexistence](/platforms/whatsapp/connect#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"groupId","in":"path","required":true,"schema":{"type":"string"},"description":"Group ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"}],"responses":{"200":{"description":"Join requests","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"joinRequests":{"type":"array","items":{"type":"object","properties":{"user":{"type":"string","description":"Phone number"},"timestamp":{"type":"integer","description":"UNIX timestamp of request"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"x-resource-group":"messages","operationId":"approveWhatsAppGroupJoinRequests","tags":["WhatsApp"],"summary":"Approve join requests","description":"Approve pending join requests for a WhatsApp group.\n\nNot available on [Coexistence](/platforms/whatsapp/connect#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"groupId","in":"path","required":true,"schema":{"type":"string"},"description":"Group ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phoneNumbers"],"properties":{"phoneNumbers":{"type":"array","items":{"type":"string"},"description":"Phone numbers to approve"}}}}}},"responses":{"200":{"description":"Requests approved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"delete":{"x-resource-group":"messages","operationId":"rejectWhatsAppGroupJoinRequests","tags":["WhatsApp"],"summary":"Reject join requests","description":"Reject pending join requests for a WhatsApp group.\n\nNot available on [Coexistence](/platforms/whatsapp/connect#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"groupId","in":"path","required":true,"schema":{"type":"string"},"description":"Group ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phoneNumbers"],"properties":{"phoneNumbers":{"type":"array","items":{"type":"string"},"description":"Phone numbers to reject"}}}}}},"responses":{"200":{"description":"Requests rejected","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/whatsapp/flows":{"get":{"x-resource-group":"accounts","operationId":"listWhatsAppFlows","tags":["WhatsApp Flows"],"summary":"List flows","description":"List all WhatsApp Flows for the Business Account (WABA) associated with the given account.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"}],"responses":{"200":{"description":"Flows retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"flows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["DRAFT","PUBLISHED","DEPRECATED","BLOCKED","THROTTLED"]},"categories":{"type":"array","items":{"type":"string"}},"validation_errors":{"type":"array","items":{"type":"object"}},"version":{"type":"integer","description":"1-based version within the flow's clone lineage (Zernio-tracked; Meta has no native versioning). Standalone flows are version 1."},"lineageId":{"type":"string","description":"Stable group key for the flow's version lineage (the root flow's ID)."}}}}}}}}},"400":{"description":"WABA ID not found on account"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}},"post":{"x-resource-group":"accounts","operationId":"createWhatsAppFlow","tags":["WhatsApp Flows"],"summary":"Create flow","description":"Create a new WhatsApp Flow in DRAFT status. Optionally clone an existing flow.\nAfter creating, upload a Flow JSON definition, then publish to make it sendable.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","name","categories"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"},"name":{"type":"string","maxLength":128,"description":"Flow display name"},"categories":{"type":"array","minItems":1,"items":{"type":"string","enum":["SIGN_UP","SIGN_IN","APPOINTMENT_BOOKING","LEAD_GENERATION","CONTACT_US","CUSTOMER_SUPPORT","SURVEY","OTHER"]},"description":"Flow categories"},"cloneFlowId":{"type":"string","description":"Optional: ID of an existing flow to clone the Flow JSON from"},"asVersion":{"type":"boolean","description":"When cloning, true keeps the clone in cloneFlowId's version lineage (auto-numbered next version); false/absent creates an independent flow. Ignored without cloneFlowId."},"endpointUri":{"type":"string","format":"uri","description":"HTTPS-only data exchange endpoint for the flow. Settable only while the flow is in DRAFT, and the flow's uploaded Flow JSON must declare data_api_version \"3.0\" for the endpoint to be used."}}},"examples":{"basic":{"summary":"Create a lead generation flow","value":{"accountId":"507f1f77bcf86cd799439011","name":"lead_capture_form","categories":["LEAD_GENERATION"]}}}}}},"responses":{"200":{"description":"Flow created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"flow":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","example":"DRAFT"},"categories":{"type":"array","items":{"type":"string"}},"version":{"type":"integer","description":"Version within the clone lineage"},"lineageId":{"type":"string","description":"Version-lineage group key"}}}}}}}},"400":{"description":"Validation error"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}}},"/v1/whatsapp/flows/{flowId}":{"get":{"x-resource-group":"accounts","operationId":"getWhatsAppFlow","tags":["WhatsApp Flows"],"summary":"Get flow","description":"Get details for a specific flow, including status, categories, validation errors, and preview URL.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"flowId","in":"path","required":true,"schema":{"type":"string"},"description":"Flow ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"},{"name":"fields","in":"query","schema":{"type":"string"},"description":"Comma-separated fields to return (default: id,name,status,categories,validation_errors,json_version,preview,data_api_version,endpoint_uri)"}],"responses":{"200":{"description":"Flow details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"flow":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"validation_errors":{"type":"array","items":{"type":"object"}},"json_version":{"type":"string"},"preview":{"type":"object","properties":{"preview_url":{"type":"string"},"expires_at":{"type":"string"}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Flow or account not found"}}},"patch":{"x-resource-group":"accounts","operationId":"updateWhatsAppFlow","tags":["WhatsApp Flows"],"summary":"Update flow","description":"Update metadata (name, categories, endpointUri) of a DRAFT flow. Published flows are immutable.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"flowId","in":"path","required":true,"schema":{"type":"string"},"description":"Flow ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"},"name":{"type":"string","maxLength":128,"description":"New flow name"},"categories":{"type":"array","minItems":1,"items":{"type":"string","enum":["SIGN_UP","SIGN_IN","APPOINTMENT_BOOKING","LEAD_GENERATION","CONTACT_US","CUSTOMER_SUPPORT","SURVEY","OTHER"]}},"endpointUri":{"type":"string","format":"uri","description":"HTTPS-only data exchange endpoint for the flow. Settable only while the flow is in DRAFT, and the flow's uploaded Flow JSON must declare data_api_version \"3.0\" for the endpoint to be used."}}}}}},"responses":{"200":{"description":"Flow updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"description":"At least one of name, categories or endpointUri is required, or flow is not in DRAFT status"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account or flow not found"}}},"delete":{"x-resource-group":"accounts","operationId":"deleteWhatsAppFlow","tags":["WhatsApp Flows"],"summary":"Delete flow","description":"Delete a DRAFT flow. This is irreversible. Only flows in DRAFT status can be deleted.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"flowId","in":"path","required":true,"schema":{"type":"string"},"description":"Flow ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"}],"responses":{"200":{"description":"Flow deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"description":"Flow is not in DRAFT status"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account or flow not found"}}}},"/v1/whatsapp/flows/{flowId}/json":{"get":{"x-resource-group":"accounts","operationId":"getWhatsAppFlowJson","tags":["WhatsApp Flows"],"summary":"Get flow JSON asset","description":"Get the flow JSON asset metadata, including a temporary download URL for the Flow JSON file.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"flowId","in":"path","required":true,"schema":{"type":"string"},"description":"Flow ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"}],"responses":{"200":{"description":"Flow JSON asset","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"assets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"flow.json"},"asset_type":{"type":"string","example":"FLOW_JSON"},"download_url":{"type":"string","description":"Temporary URL to download the flow JSON"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}},"put":{"x-resource-group":"accounts","operationId":"uploadWhatsAppFlowJson","tags":["WhatsApp Flows"],"summary":"Upload flow JSON","description":"Upload or update the Flow JSON for a DRAFT flow. The Flow JSON defines all screens,\ncomponents (text inputs, dropdowns, date pickers, etc.), and navigation.\n\nMeta validates the JSON on upload and returns any validation errors.\nSee: https://developers.facebook.com/docs/whatsapp/flows/reference/flowjson\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"flowId","in":"path","required":true,"schema":{"type":"string"},"description":"Flow ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","flow_json"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"},"flow_json":{"description":"The Flow JSON content. Pass as a JSON object or a JSON string.","oneOf":[{"type":"object"},{"type":"string"}]}}},"examples":{"simple_form":{"summary":"Simple lead capture form","value":{"accountId":"507f1f77bcf86cd799439011","flow_json":{"version":"6.0","screens":[{"id":"LEAD_FORM","title":"Get a Quote","terminal":true,"success":true,"layout":{"type":"SingleColumnLayout","children":[{"type":"TextInput","name":"full_name","label":"Full Name","required":true,"input-type":"text"},{"type":"TextInput","name":"email","label":"Email","required":true,"input-type":"email"},{"type":"Footer","label":"Submit","on-click-action":{"name":"complete","payload":{"full_name":"${form.full_name}","email":"${form.email}"}}}]}}]}}}}}}},"responses":{"200":{"description":"Flow JSON uploaded","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"validation_errors":{"type":"array","description":"Empty array if valid; otherwise, contains validation error details from Meta","items":{"type":"object","properties":{"error":{"type":"string"},"error_type":{"type":"string"},"message":{"type":"string"},"line_start":{"type":"integer"},"line_end":{"type":"integer"},"column_start":{"type":"integer"},"column_end":{"type":"integer"}}}}}}}}},"400":{"description":"Invalid JSON or flow is not in DRAFT status"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}}},"/v1/whatsapp/flows/{flowId}/preview":{"get":{"x-resource-group":"accounts","operationId":"getWhatsAppFlowPreview","tags":["WhatsApp Flows"],"summary":"Get flow preview URL","description":"Get Meta's public web-preview URL for a flow (drafts included), embeddable as an\ninteractive iframe. The link is reused across calls (valid ~30 days); pass\ninvalidate=true to mint a fresh one (the previous link stops working).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"flowId","in":"path","required":true,"schema":{"type":"string"},"description":"Flow ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"},{"name":"invalidate","in":"query","required":false,"schema":{"type":"boolean"},"description":"Mint a fresh preview link (default false)"}],"responses":{"200":{"description":"Preview URL","content":{"application/json":{"schema":{"type":"object","properties":{"preview_url":{"type":["string","null"]},"expires_at":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Flow or account not found"}}}},"/v1/whatsapp/flows/{flowId}/versions":{"get":{"x-resource-group":"accounts","operationId":"listWhatsAppFlowVersions","tags":["WhatsApp Flows"],"summary":"List flow versions","description":"List the flow's version history (the clone lineage Zernio tracks, since Meta has no\nnative versioning), newest version first. Each entry is enriched with the version's\nlive name and status from Meta. A flow with no lineage returns only itself as version 1.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"flowId","in":"path","required":true,"schema":{"type":"string"},"description":"Flow ID"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"}],"responses":{"200":{"description":"Version history","content":{"application/json":{"schema":{"type":"object","properties":{"versions":{"type":"array","items":{"type":"object","properties":{"flowId":{"type":"string"},"version":{"type":"integer"},"parentFlowId":{"type":["string","null"]},"name":{"type":["string","null"]},"status":{"type":["string","null"]},"missing":{"type":"boolean","description":"True when Meta no longer has this flow"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Flow or account not found"}}}},"/v1/whatsapp/flows/{flowId}/publish":{"post":{"x-resource-group":"accounts","operationId":"publishWhatsAppFlow","tags":["WhatsApp Flows"],"summary":"Publish flow","description":"Publish a DRAFT flow. This is irreversible. Once published, the flow and its JSON\nbecome immutable and the flow can be sent to users. To update a published flow,\ncreate a new flow (optionally cloning this one via cloneFlowId).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"flowId","in":"path","required":true,"schema":{"type":"string"},"description":"Flow ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"}}}}}},"responses":{"200":{"description":"Flow published","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"description":"Flow is not in DRAFT status or has validation errors"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}}},"/v1/whatsapp/flows/{flowId}/deprecate":{"post":{"x-resource-group":"accounts","operationId":"deprecateWhatsAppFlow","tags":["WhatsApp Flows"],"summary":"Deprecate flow","description":"Deprecate a PUBLISHED flow. This is irreversible. Deprecated flows cannot be sent\nor opened, but existing active sessions may continue until they complete.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"flowId","in":"path","required":true,"schema":{"type":"string"},"description":"Flow ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"}}}}}},"responses":{"200":{"description":"Flow deprecated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"description":"Flow is not in PUBLISHED status"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}}},"/v1/whatsapp/flows/encryption-key":{"get":{"x-resource-group":"accounts","operationId":"getWhatsAppFlowsEncryptionKey","tags":["WhatsApp Flows"],"summary":"Get Flows encryption key status","description":"Read the RSA business public key registered on the phone number for WhatsApp Flows endpoint encryption. Only one key is active per phone number at a time.\n\n### Why the key matters\n\n- Flows that use flow_action: data_exchange (an endpoint-backed flow) stop working at runtime until the endpoint serves the matching private key.\n- Meta rejects publish with error code 139002 (\"Missing Flows Signed Public Key\") when no key is registered.\n\n### Reading the status\n\n`registered` reflects whether a key is present, never `signatureStatus` alone. Meta reports an unregistered key as MISMATCH rather than a null/absent value.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"}],"responses":{"200":{"description":"Encryption key status retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"publicKey":{"type":["string","null"],"description":"The registered RSA public key in PEM format, or null when none is registered."},"signatureStatus":{"type":["string","null"],"description":"VALID (key matches Meta's records) or MISMATCH (no key registered, or the key does not match); null when unknown.","enum":["VALID","MISMATCH"]},"registered":{"type":"boolean","description":"Whether a key is currently registered. Derived from publicKey, not signatureStatus."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"},"404":{"description":"WhatsApp account not found"},"502":{"description":"Meta rejected the request"}}},"post":{"x-resource-group":"accounts","operationId":"setWhatsAppFlowsEncryptionKey","tags":["WhatsApp Flows"],"summary":"Register a Flows encryption key","description":"Register (or replace) the RSA business public key for WhatsApp Flows endpoint encryption on the phone number.\n\n- Uploading a new key replaces the previous one: only one key is active per phone number.\n- The corresponding private key must be served by the flow's endpoint. Otherwise endpoint-backed flows (flow_action: data_exchange) will fail at runtime even though the key is registered.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","businessPublicKey"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"},"businessPublicKey":{"type":"string","description":"RSA public key in PEM format. Rejected if it is a private key or not a valid RSA public key PEM."}}}}}},"responses":{"200":{"description":"Encryption key registered","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"},"404":{"description":"WhatsApp account not found"},"502":{"description":"Meta rejected the request"}}}},"/v1/whatsapp/flows/send":{"post":{"x-resource-group":"messages","operationId":"sendWhatsAppFlowMessage","tags":["WhatsApp Flows"],"summary":"Send flow message","description":"Send a published flow as an interactive message with a CTA button.\nWhen the recipient taps the button, the flow opens natively in WhatsApp.\nFlow responses are received via webhooks.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","to","flow_id","flow_cta","body"],"properties":{"accountId":{"type":"string","description":"WhatsApp account ID"},"to":{"type":"string","description":"Recipient phone number (E.164 format, e.g. +1234567890)"},"flow_id":{"type":"string","description":"Published flow ID"},"flow_cta":{"type":"string","maxLength":20,"description":"CTA button text (e.g. 'Book Now', 'Sign Up')"},"flow_action":{"type":"string","enum":["navigate","data_exchange"],"default":"navigate","description":"Action type: navigate opens a screen directly, data_exchange hits your endpoint first"},"flow_token":{"type":"string","maxLength":200,"description":"Unique token to correlate responses. If omitted, auto-generated as '<flowId>:<uuid>' so the response can be attributed to this flow in the Flow Responses view."},"flow_action_payload":{"type":"object","properties":{"screen":{"type":"string","description":"First screen ID to navigate to"},"data":{"type":"object","description":"Optional data to pass to the screen"}}},"body":{"type":"string","description":"Message body text"},"header":{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"}}},"footer":{"type":"string","description":"Optional footer text"},"draft":{"type":"boolean","description":"Set true to test an unpublished (DRAFT) flow"}}},"examples":{"basic":{"summary":"Send a lead capture flow","value":{"accountId":"507f1f77bcf86cd799439011","to":"+1234567890","flow_id":"1234567890","flow_cta":"Get a Quote","flow_action":"navigate","flow_action_payload":{"screen":"LEAD_FORM"},"body":"Hi! Fill out this quick form to get a personalized quote."}}}}}},"responses":{"200":{"description":"Flow message sent","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"messageId":{"type":"string","description":"WhatsApp message ID (WAMID)"}}}}}},"400":{"description":"Validation error or missing phone number ID"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}}},"/v1/whatsapp/flow-responses":{"get":{"x-resource-group":"messages","operationId":"listWhatsAppFlowResponses","tags":["WhatsApp Flows"],"summary":"List flow responses","description":"List the responses customers submitted when completing a flow (parsed from the nfm_reply messages received via webhook), newest first.\n\nScope to a single flow with `flowId`. It matches responses whose flow_token carries the `<flowId>:` prefix that Zernio stamps on auto-generated tokens at send time.\n\nResponses sent with a custom integrator-supplied flow_token are not attributed to a flow.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"},{"name":"flowId","in":"query","required":false,"schema":{"type":"string"},"description":"Scope to responses for this flow"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"default":50},"description":"Max responses to return"}],"responses":{"200":{"description":"Flow responses","content":{"application/json":{"schema":{"type":"object","properties":{"responses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Message ID"},"receivedAt":{"type":"string","format":"date-time"},"from":{"type":["string","null"],"description":"Sender wa_id / phone"},"senderName":{"type":["string","null"]},"conversationId":{"type":["string","null"]},"flowToken":{"type":["string","null"]},"data":{"type":"object","description":"Submitted field values (flow_token removed)"},"raw":{"type":["string","null"],"description":"Raw response_json string"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}}},"/v1/contacts":{"get":{"x-resource-group":"contacts","operationId":"listContacts","summary":"List contacts","description":"List and search contacts for a profile. Supports filtering by tags, platform, subscription status, and text search on name, email and company.","tags":["Contacts"],"parameters":[{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Filter by profile. Omit to list across all profiles. Matches the profile recorded on the contact itself, which is set when the contact is created and is independent of the profile its account currently belongs to. Filter by accountId to list a contact through its channel instead."},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Filter by the SocialAccount that owns the contact channel. Contacts are resolved through their channels, so the profileId contact filter is not applied while accountId is set. A profileId sent alongside is still access-checked and still scopes the returned filters.tags list."},{"name":"search","in":"query","schema":{"type":"string"},"description":"Case-insensitive substring match on the contact name, email and company. Phone numbers and other platform identifiers are not matched: they live on the contact channel, not on the contact. To reach a contact from an inbox webhook, use the conversation.contactId it already carries."},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"tags","in":"query","schema":{"type":"string"},"description":"Comma-separated tags, matches contacts carrying any of them"},{"name":"platform","in":"query","schema":{"type":"string","enum":["instagram","facebook","telegram","twitter","bluesky","reddit","whatsapp","slack","sms"]}},{"name":"isSubscribed","in":"query","schema":{"type":"string","enum":["true","false"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},{"name":"skip","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Contacts list with pagination and filter metadata","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"company":{"type":"string"},"avatarUrl":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"isSubscribed":{"type":"boolean"},"isBlocked":{"type":"boolean"},"lastMessageSentAt":{"type":"string","format":"date-time"},"lastMessageReceivedAt":{"type":"string","format":"date-time"},"messagesSentCount":{"type":"integer"},"messagesReceivedCount":{"type":"integer"},"customFields":{"type":"object"},"notes":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"platform":{"type":"string"},"platformIdentifier":{"type":"string"},"displayIdentifier":{"type":"string"}}}},"filters":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}}}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"skip":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"x-resource-group":"contacts","operationId":"createContact","summary":"Create contact","description":"Create a new contact. Optionally create a platform channel in the same request by providing accountId, platform, and platformIdentifier.","tags":["Contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","name"],"properties":{"profileId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"company":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"isSubscribed":{"type":"boolean","default":true},"notes":{"type":"string"},"accountId":{"type":"string","description":"Optional. Creates a channel if provided with platform + platformIdentifier"},"platform":{"type":"string","enum":["instagram","facebook","telegram","twitter","bluesky","reddit","whatsapp","slack","sms"],"description":"Channel platform. Only the enum values support contact channels; any other platform is rejected with code platform_not_supported."},"platformIdentifier":{"type":"string"},"displayIdentifier":{"type":"string"}}}}}},"responses":{"200":{"description":"Contact created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"contact":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"company":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"isSubscribed":{"type":"boolean"},"isBlocked":{"type":"boolean"},"customFields":{"type":"object"},"notes":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"channel":{"type":"object","description":"Created when accountId, platform, and platformIdentifier are provided","properties":{"id":{"type":"string"},"platform":{"type":"string"},"platformIdentifier":{"type":"string"},"displayIdentifier":{"type":"string"}}},"warning":{"type":"string"}}}}}},"400":{"x-summary":"The channel fields are invalid: send accountId, platform and platformIdentifier together on a platform that supports contact channels.","description":"Invalid request. Channel fields are all-or-nothing: accountId, platform and platformIdentifier must be sent together (code: missing_required_field). A platform outside the enum does not support contact channels (code: platform_not_supported, details.supportedPlatforms lists the valid values)."},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"x-summary":"A channel with this platformIdentifier already exists on the account: use the existing contact or a different identifier.","description":"Duplicate channel. The platformIdentifier is already bound to a channel on this accountId."}}}},"/v1/contacts/{contactId}":{"get":{"x-resource-group":"contacts","operationId":"getContact","summary":"Get contact","description":"Returns a contact with all associated messaging channels.","tags":["Contacts"],"parameters":[{"name":"contactId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Contact with channels","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"contact":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"company":{"type":"string"},"avatarUrl":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"isSubscribed":{"type":"boolean"},"isBlocked":{"type":"boolean"},"messagesSentCount":{"type":"integer","description":"Messages sent to the contact, derived live from message history across all linked conversations."},"messagesReceivedCount":{"type":"integer","description":"Messages received from the contact, derived live from message history across all linked conversations."},"lastMessageSentAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the most recent outgoing message, or null if none."},"lastMessageReceivedAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the most recent incoming message, or null if none."},"customFields":{"type":"object"},"notes":{"type":"string"},"conversationIds":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"channels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"platform":{"type":"string"},"platformIdentifier":{"type":"string"},"displayIdentifier":{"type":"string"},"isSubscribed":{"type":"boolean"},"conversationId":{"type":"string"},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"Most recent message (either direction) in this channel's conversation, or null if none."},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"x-resource-group":"contacts","operationId":"updateContact","summary":"Update contact","description":"Update one or more fields on a contact. Only provided fields are changed.","tags":["Contacts"],"parameters":[{"name":"contactId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"company":{"type":"string"},"avatarUrl":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"isSubscribed":{"type":"boolean"},"isBlocked":{"type":"boolean"},"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"Contact updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"contact":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"company":{"type":"string"},"avatarUrl":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"isSubscribed":{"type":"boolean"},"isBlocked":{"type":"boolean"},"notes":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"x-resource-group":"contacts","operationId":"deleteContact","summary":"Delete contact","description":"Permanently deletes a contact and all associated channels.","tags":["Contacts"],"parameters":[{"name":"contactId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Contact deleted"},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/contacts/{contactId}/channels":{"get":{"x-resource-group":"contacts","operationId":"getContactChannels","summary":"List channels for a contact","description":"Returns all messaging channels linked to a contact (e.g. Instagram DM, Telegram, WhatsApp).","tags":["Contacts"],"parameters":[{"name":"contactId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of contact channels","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"channels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"platform":{"type":"string"},"platformIdentifier":{"type":"string"},"displayIdentifier":{"type":"string"},"isSubscribed":{"type":"boolean"},"conversationId":{"type":"string"},"metadata":{"type":"object"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/contacts/bulk":{"post":{"x-resource-group":"contacts","operationId":"bulkCreateContacts","summary":"Bulk create contacts","description":"Import up to 1000 contacts at a time. Skips duplicates, merging any new tags onto the existing contact.\n\n### Accounts and platform\n\n- accountId is required whenever contacts carry a platformIdentifier (or a row-level accountId).\n- platform is always derived from the resolved account, never used to decide whether channels are created. A mismatched platform 404s as account not found.\n\n### Per-contact validation\n\n- When accountId is set, each contact must carry a platformIdentifier. A row missing it is rejected individually (reported in errors[], HTTP 200), not a 400 for the whole import.\n- On phone platforms (whatsapp, sms) the platformIdentifier is normalized to digits. A value that is not phone-shaped is rejected per contact and reported in errors[], not imported.\n","tags":["Contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","contacts"],"properties":{"profileId":{"type":"string"},"accountId":{"type":"string","description":"Required when contacts carry channel data (platformIdentifier or a row-level accountId). Omit for a plain CRM import with no channels."},"platform":{"type":"string","description":"Ignored when accountId is set: the platform is derived from the resolved account. Only relevant to disambiguate accountId lookup; a mismatch 404s."},"contacts":{"type":"array","maxItems":1000,"items":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"platformIdentifier":{"type":"string","description":"Required when the top-level accountId is set (channel mode). A row missing it in that mode is rejected individually and reported in errors[], not a 400 for the whole import."},"displayIdentifier":{"type":"string"},"email":{"type":"string"},"company":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}}}}}}}},"responses":{"200":{"description":"Bulk import results","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"created":{"type":"integer"},"skipped":{"type":"integer"},"errors":{"type":"array","items":{"type":"string"},"description":"Per-contact failures, e.g. an identifier that is not a valid phone number"},"total":{"type":"integer"}}}}}},"400":{"x-summary":"The import is invalid: every contact needs a name, and rows with channel fields need a supported account.","description":"Returned when:\n\n- a contact is missing the required field name;\n- a row carries platformIdentifier/accountId with no top-level accountId to attach it to;\n- an accountId is on a platform with no contact channels, which rejects the whole import (code: platform_not_supported, details.supportedPlatforms lists the valid values).\n\nA row missing platformIdentifier while accountId IS set is not a 400: it is reported in errors[] under a 200."},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/contacts/{contactId}/fields/{slug}":{"put":{"x-resource-group":"contacts","operationId":"setContactFieldValue","summary":"Set custom field value","description":"Set or overwrite a custom field value on a contact. The value type must match the field definition.","tags":["Custom Fields"],"parameters":[{"name":"contactId","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["value"],"properties":{"value":{"description":"Field value (type depends on field definition)"}}}}}},"responses":{"200":{"description":"Field value set"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"x-resource-group":"contacts","operationId":"clearContactFieldValue","summary":"Clear custom field value","description":"Remove a custom field value from a contact. The field definition is not affected.","tags":["Custom Fields"],"parameters":[{"name":"contactId","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Field value cleared"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/custom-fields":{"get":{"x-resource-group":"accounts","operationId":"listCustomFields","summary":"List custom field definitions","description":"Returns all custom field definitions. Optionally filter by profile.","tags":["Custom Fields"],"parameters":[{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Filter by profile. Omit to list across all profiles"}],"responses":{"200":{"description":"List of custom field definitions","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"fields":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"type":{"type":"string","enum":["text","number","date","boolean","select"]},"options":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"400":{"description":"Invalid profileId format"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"x-resource-group":"accounts","operationId":"createCustomField","summary":"Create custom field","description":"Create a new custom field definition. Supported types are text, number, date, boolean, and select.","tags":["Custom Fields"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","name","type"],"properties":{"profileId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string","description":"Auto-generated from name if not provided"},"type":{"type":"string","enum":["text","number","date","boolean","select"]},"options":{"type":"array","items":{"type":"string"},"description":"Required for select type"}}}}}},"responses":{"200":{"description":"Custom field created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"field":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"type":{"type":"string","enum":["text","number","date","boolean","select"]},"options":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Invalid request body"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"description":"Duplicate slug"}}}},"/v1/custom-fields/{fieldId}":{"patch":{"x-resource-group":"accounts","operationId":"updateCustomField","summary":"Update custom field","description":"Update a custom field definition. The field type cannot be changed after creation.","tags":["Custom Fields"],"parameters":[{"name":"fieldId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"options":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Custom field updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"field":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"type":{"type":"string"},"options":{"type":"array","items":{"type":"string"}}}}}}}}},"400":{"description":"Invalid fieldId or request body"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"x-resource-group":"accounts","operationId":"deleteCustomField","summary":"Delete custom field","description":"Delete a custom field definition and remove its values from all contacts.","tags":["Custom Fields"],"parameters":[{"name":"fieldId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Custom field deleted"},"400":{"description":"Invalid fieldId format"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/broadcasts":{"get":{"x-resource-group":"messages","operationId":"listBroadcasts","summary":"List broadcasts","description":"Returns broadcasts with delivery stats. Filter by status, platform, or profile.","tags":["Broadcasts"],"parameters":[{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Filter by profile. Omit to list across all profiles"},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","scheduled","sending","completed","failed","cancelled"]}},{"name":"platform","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"skip","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Broadcasts list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"broadcasts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"platform":{"type":"string"},"accountId":{"type":"string"},"accountName":{"type":"string","description":"Display name of the sending account"},"status":{"type":"string","enum":["draft","scheduled","sending","completed","failed","cancelled"]},"messagePreview":{"type":"string","description":"Template name or message text snippet"},"scheduledAt":{"type":"string","format":"date-time"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"},"recipientCount":{"type":"integer"},"sentCount":{"type":"integer"},"deliveredCount":{"type":"integer"},"readCount":{"type":"integer"},"failedCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"skip":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"x-resource-group":"messages","operationId":"createBroadcast","summary":"Create broadcast draft","description":"Create a broadcast in draft status. Add recipients and then send or schedule it.","tags":["Broadcasts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","accountId","platform","name"],"properties":{"profileId":{"type":"string"},"accountId":{"type":"string"},"platform":{"type":"string","enum":["instagram","facebook","telegram","twitter","bluesky","reddit","whatsapp","sms","slack","imessage"]},"name":{"type":"string"},"description":{"type":"string"},"message":{"type":"object","properties":{"text":{"type":"string","description":"Required on every platform except WhatsApp (which sends `template`) and an SMS broadcast that carries attachments."},"attachments":{"type":"array","maxItems":10,"description":"SMS only: sent as MMS media, one media_url per attachment. Each url must be public http(s); JPEG, PNG, GIF, WEBP, MP4 or 3GPP under 1 MB (checked at create when the host answers a HEAD request; Telnyx enforces the 1 MB total per message at send).","items":{"type":"object","properties":{"type":{"type":"string"},"url":{"type":"string"},"filename":{"type":"string"}}}},"messageTag":{"type":"string","enum":["CONFIRMED_EVENT_UPDATE","POST_PURCHASE_UPDATE","ACCOUNT_UPDATE","HUMAN_AGENT"],"description":"Not usable: a broadcast only reaches people within the 24h window. HUMAN_AGENT is rejected with a 400 because it is only for replies typed by a person, and Meta retired the other tags."}}},"template":{"type":"object","description":"WhatsApp template (required when platform is whatsapp)","properties":{"name":{"type":"string"},"language":{"type":"string"},"components":{"type":"array","items":{"type":"object","additionalProperties":true}},"variableMapping":{"type":"object","description":"Maps template variable positions (\"1\", \"2\") to contact fields or static values. Resolved per recipient at send time.","additionalProperties":{"type":"object","properties":{"field":{"type":"string","enum":["name","phone","email","company","custom"]},"customValue":{"type":"string","description":"Static value used when field is \"custom\""}}}}}},"segmentFilters":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"isSubscribed":{"type":"boolean"},"customFields":{"type":"object","additionalProperties":true,"description":"Custom field values a contact must hold, keyed by field slug. Exact match per key (type included: 5 does not match \"5\"); every key must match."}}}}}}}},"responses":{"200":{"description":"Broadcast created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"broadcast":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"platform":{"type":"string"},"accountId":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/broadcasts/{broadcastId}":{"get":{"x-resource-group":"messages","operationId":"getBroadcast","summary":"Get broadcast details","description":"Returns a broadcast with its full configuration and delivery stats.","tags":["Broadcasts"],"parameters":[{"name":"broadcastId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Broadcast details with stats","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"broadcast":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"platform":{"type":"string"},"accountId":{"type":"string"},"message":{"type":"object","properties":{"text":{"type":"string"}}},"template":{"type":"object","properties":{"name":{"type":"string"},"language":{"type":"string"}}},"segmentFilters":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"isSubscribed":{"type":"boolean"},"customFields":{"type":"object","additionalProperties":true}}},"status":{"type":"string","enum":["draft","scheduled","sending","completed","failed","cancelled"]},"scheduledAt":{"type":"string","format":"date-time"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"},"recipientCount":{"type":"integer"},"sentCount":{"type":"integer"},"deliveredCount":{"type":"integer"},"readCount":{"type":"integer"},"failedCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"x-resource-group":"messages","operationId":"updateBroadcast","summary":"Update broadcast","description":"Update a broadcast's name, message, template, or segment filters. Only draft broadcasts can be updated.","tags":["Broadcasts"],"parameters":[{"name":"broadcastId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"message":{"type":"object","description":"Generic message payload (used for non-WhatsApp platforms).","properties":{"text":{"type":"string"},"attachments":{"type":"array","maxItems":10,"description":"SMS only: sent as MMS media.","items":{"type":"object","properties":{"type":{"type":"string"},"url":{"type":"string"},"filename":{"type":"string"}}}},"messageTag":{"type":"string","enum":["CONFIRMED_EVENT_UPDATE","POST_PURCHASE_UPDATE","ACCOUNT_UPDATE","HUMAN_AGENT"],"description":"Instagram and Facebook only. See createBroadcast."}}},"template":{"type":"object","description":"WhatsApp template payload (used when platform is `whatsapp`).","properties":{"name":{"type":"string"},"language":{"type":"string"},"variableMapping":{"type":"object","description":"Maps template variable positions to contact fields. Keys are position strings (\"1\", \"2\"); values are { field, customValue }.","additionalProperties":{"type":"object","properties":{"field":{"type":"string","enum":["name","phone","email","company","custom"]},"customValue":{"type":"string"}}}}}},"segmentFilters":{"type":"object","description":"Recipient segment filters (tags, channels, subscription state)."}}}}}},"responses":{"200":{"description":"Broadcast updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"broadcast":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"x-resource-group":"messages","operationId":"deleteBroadcast","summary":"Delete broadcast","description":"Permanently delete a broadcast. Only drafts can be deleted.","tags":["Broadcasts"],"parameters":[{"name":"broadcastId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Broadcast deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/broadcasts/{broadcastId}/send":{"post":{"x-resource-group":"messages","operationId":"sendBroadcast","summary":"Send broadcast now","description":"Immediately start sending a draft broadcast to its recipients.","tags":["Broadcasts"],"parameters":[{"name":"broadcastId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Broadcast sending started","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"string","enum":["sending","completed","failed"],"description":"Current broadcast status after processing first batch"},"sent":{"type":"integer","description":"Recipients sent in this batch"},"failed":{"type":"integer","description":"Recipients failed in this batch"},"recipientCount":{"type":"integer","description":"Total recipient count"}}}}}},"400":{"description":"Invalid status or no recipients"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/broadcasts/{broadcastId}/schedule":{"post":{"x-resource-group":"messages","operationId":"scheduleBroadcast","summary":"Schedule broadcast for later","description":"Schedule a draft broadcast, or move the date of an already scheduled one, to a future date and time.","tags":["Broadcasts"],"parameters":[{"name":"broadcastId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["scheduledAt"],"properties":{"scheduledAt":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"Broadcast scheduled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"broadcast":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"scheduledAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Invalid date or status"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/broadcasts/{broadcastId}/cancel":{"post":{"x-resource-group":"messages","operationId":"cancelBroadcast","summary":"Cancel broadcast","description":"Cancel a scheduled or in-progress broadcast. Already-sent messages are not affected.","tags":["Broadcasts"],"parameters":[{"name":"broadcastId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Broadcast cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"broadcast":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}}}}}}}},"400":{"description":"Cannot cancel in current status"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/broadcasts/{broadcastId}/recipients":{"get":{"x-resource-group":"messages","operationId":"listBroadcastRecipients","summary":"List broadcast recipients","description":"Returns recipients for a broadcast with individual delivery status. Filter by status.","tags":["Broadcasts"],"parameters":[{"name":"broadcastId","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","sent","delivered","read","failed"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"skip","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Recipients list with delivery status","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"recipients":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"contactId":{"type":"string"},"channelId":{"type":"string"},"platformIdentifier":{"type":"string"},"contactName":{"type":["string","null"]},"status":{"type":"string","enum":["pending","sent","delivered","read","failed"]},"messageId":{"type":"string"},"error":{"type":"string"},"errorCode":{"type":["integer","null"],"description":"Meta WhatsApp error code (e.g. 131049 for antispam, 131021 for invalid phone, 131026 for re-engagement required). Only populated for status=failed."},"errorExplanation":{"type":["string","null"],"description":"Plain-language translation of errorCode (e.g. for 131026, that the recipient has likely opted out of marketing messages). Null for unmapped codes; fall back to error."},"errorTraceId":{"type":["string","null"],"description":"Meta trace id (fbtrace_id) for the failed send. Quote this when escalating to Meta Direct Support. Only populated for status=failed on Meta platforms."},"sentAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":"string","format":"date-time"},"readAt":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"skip":{"type":"integer"},"hasMore":{"type":"boolean"}}},"summary":{"type":"object","description":"Delivery totals across all recipients in the broadcast, independent of pagination and status filtering.","properties":{"total":{"type":"integer"},"pending":{"type":"integer"},"sent":{"type":"integer"},"delivered":{"type":"integer"},"read":{"type":"integer"},"failed":{"type":"integer"}}}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"x-resource-group":"messages","operationId":"addBroadcastRecipients","summary":"Add recipients to a broadcast","description":"Add recipients by contact IDs, raw phone numbers, or from the broadcast's segment filters.","tags":["Broadcasts"],"parameters":[{"name":"broadcastId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactIds":{"type":"array","items":{"type":"string"},"description":"Specific contact IDs to add. Zernio contact ids (24-character hex), as returned by the list-contacts endpoint. A platform identifier such as a WhatsApp wa_id is rejected with 400; use phones for raw numbers."},"phones":{"type":"array","items":{"type":"string"},"maxItems":20000,"description":"Raw phone numbers (auto-creates contacts). Useful for WhatsApp/Telegram manual entry"},"useSegment":{"type":"boolean","description":"Auto-populate from broadcast segment filters"}}}}}},"responses":{"200":{"description":"Recipients added","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"added":{"type":"integer","description":"Number of recipients successfully added"},"skipped":{"type":"integer","description":"Number skipped (duplicates or missing channels)"}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/support/runs":{"get":{"x-resource-group":"admin-plane","operationId":"listSupportAnswers","tags":["Support Assistant"],"summary":"List a thread's support answers","description":"Lists the runs of one thread that your team started, with each question and its answer, oldest first.\n\n- Replies from the Zernio team after a support ticket arrive by email and are not included.\n- Runs are kept for 90 days.\n\nPage through a long thread with `limit` and `cursor`: pass `nextCursor` as `cursor` until it is null.\n","parameters":[{"name":"threadId","in":"query","required":true,"schema":{"type":"string"},"description":"The thread to list, as returned by `POST /v1/support/runs`."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Runs per page."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pass `nextCursor` from the previous page."}],"responses":{"200":{"description":"The thread's runs, oldest first","content":{"application/json":{"schema":{"type":"object","required":["runs","nextCursor"],"properties":{"runs":{"type":"array","items":{"$ref":"#/components/schemas/SupportRun"}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"A card is required (code `payment_method_required`) or the last payment failed (code `payment_required`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Code `insufficient_permissions`: not an unrestricted API key, or a read-only, restricted or profile-scoped user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Code `support_thread_not_found`: no run in this thread was started by your team, or its runs are older than 90 days.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"x-resource-group":"admin-plane","operationId":"askSupportQuestion","tags":["Support Assistant"],"summary":"Ask a support question","description":"Asks the Zernio Support Assistant a question about your workspace. Each question starts a run that answers asynchronously.\n\n### How a run works\n\n1. This returns 202 with a `runId`.\n2. The answer arrives through the `support.run.completed` and `support.run.failed` webhooks. `GET /v1/support/runs/{runId}` is the fallback.\n3. When the assistant finds a problem on Zernio's side, it opens a support ticket with the team (see `supportTicket` on the run) and the run ends as `needs_human`.\n\nPass `threadId` to continue an earlier conversation, and `context` to point the assistant at a post, account, profile or a failed request (its `X-Request-Id`).\n\n### Pricing\n\nYou pay per question, once it finishes. The exact amount charged is the run's `costUsd`.\n\n| Question | You pay |\n| --- | --- |\n| Typical question | $0.10 to $0.50 |\n| Most one question can cost | Its `maxCostUsd`: $0.50 to $3, $3 by default |\n| Handed to the Zernio team (`needs_human`) | Charged like an answered question |\n| Failed or expired | $0 |\n| All questions in a UTC month | At most $100 per account |\n\nNear its `maxCostUsd` a run stops investigating and answers with what it found so far, so it never charges more than the cap. With nothing to answer yet, it fails and costs nothing. Charges appear as \"Support API\" on your invoice.\n\n### Requirements and limits\n\n- Requires an unrestricted API key, usage-based billing and a card on file.\n- Limits per account: 3 active runs and $100 of runs per UTC month.\n- Send an Idempotency-Key header to make retries safe.\n","parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["message"],"properties":{"message":{"type":"string","minLength":1,"maxLength":10000,"description":"The question. Leading and trailing whitespace is trimmed."},"threadId":{"type":"string","description":"Continue this thread. The thread must have a run started by your team, and no run in progress."},"context":{"type":"object","additionalProperties":false,"description":"Ids the assistant should look at. postId, accountId and profileId must belong to your workspace (404 otherwise).","properties":{"postId":{"type":"string"},"accountId":{"type":"string"},"profileId":{"type":"string"},"requestId":{"type":"string","maxLength":128,"pattern":"^[\\w.-]{1,128}$","description":"The X-Request-Id of a call you want explained. The assistant reads that request's logged record. Not checked up front."}}},"maxCostUsd":{"type":"number","minimum":0.5,"maximum":3,"default":3,"description":"Cost cap for this run, in USD. The run stops at the cap and bills at most this amount."}}},"example":{"message":"Why did my Instagram post fail to publish?","context":{"postId":"64f0a1b2c3d4e5f6a7b8c9d0"}}}}},"responses":{"202":{"description":"Run accepted","content":{"application/json":{"schema":{"type":"object","required":["runId","threadId","status","pollAfterSeconds"],"properties":{"runId":{"type":"string"},"threadId":{"type":"string"},"status":{"type":"string","enum":["queued"]},"pollAfterSeconds":{"type":"integer","description":"Seconds to wait before the first poll."}}},"example":{"runId":"64f0a1b2c3d4e5f6a7b8c9d1","threadId":"64f0a1b2c3d4e5f6a7b8c9d2","status":"queued","pollAfterSeconds":5}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"A card is required or the last payment failed: add or update the card in Billing.","description":"A card is required (code `payment_method_required`), the last payment failed (code `payment_required`), or, on balance billing, the balance is at $0 (code `insufficient_balance` or `usage_limit_reached`). Fix it in Billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Code `insufficient_permissions`: the credential is not an unrestricted API key, or the user is read-only, restricted or profile-scoped.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Code `support_thread_not_found` (`threadId`), `post_not_found`, `account_not_found` or `profile_not_found` (`context.*`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"x-summary":"A run is already queued or running, or billing setup is incomplete: poll the existing run first, or contact support.","description":"Code `support_run_in_progress`: the thread already has a run queued or running, so poll it first. Code `billing_setup_incomplete`: no billing customer to attach a card to, contact support. Also returned while a request with the same Idempotency-Key is still processing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"x-summary":"The Support Assistant needs a usage-based plan, or the Idempotency-Key belongs to a different request: upgrade or use a new key.","description":"Code `usage_billing_required`: the Support Assistant needs a usage-based plan. Also returned when an Idempotency-Key is reused with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"x-summary":"Three runs are already active or the monthly cap would be exceeded: wait for `Retry-After` before retrying.","description":"Code `support_active_runs_limit`: 3 runs are already active, retry when one finishes. Code `support_monthly_cap_exceeded`: this run could take the account past $100 for the UTC month; `Retry-After` runs until the next month starts, which can be weeks.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/v1/support/runs/{runId}":{"get":{"x-resource-group":"admin-plane","operationId":"getSupportAnswer","tags":["Support Assistant"],"summary":"Get a support answer","description":"Returns a run started by your team, with the answer once it is ready.\n\nPrefer the `support.run.completed` and `support.run.failed` webhooks. Use this as the fallback, waiting `pollAfterSeconds` between polls.\n\n`costUsd` is the amount billed for the question, never above `maxCostUsd`, and 0 for a failed run (pricing on Ask a support question).\n","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportRun"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"A card is required (code `payment_method_required`) or the last payment failed (code `payment_required`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Code `insufficient_permissions`: not an unrestricted API key, or a read-only, restricted or profile-scoped user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Code `support_run_not_found`: no such run, or it was not started by your team.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/workflows":{"get":{"x-resource-group":"accounts","operationId":"listWorkflows","summary":"List workflows","description":"Returns workflows with run stats. Filter by status or profile.","tags":["Workflows"],"parameters":[{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Filter by profile. Omit to list across all profiles"},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","active","paused"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"skip","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Workflows list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"workflows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"platform":{"type":"string"},"accountId":{"type":"string"},"accountName":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused"]},"nodeCount":{"type":"integer"},"totalStarted":{"type":"integer"},"totalCompleted":{"type":"integer"},"totalExited":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"skip":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"x-resource-group":"accounts","operationId":"createWorkflow","summary":"Create workflow","description":"Create a branching conversation workflow (draft) from a node/edge graph. Created in `draft` status; activate it to start matching inbound messages. The graph is validated structurally; completeness (a trigger node + reachable entry) is required at activation.\n","tags":["Workflows"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","accountId","name"],"properties":{"profileId":{"type":"string"},"accountId":{"type":"string"},"platform":{"type":"string","enum":["whatsapp","instagram","facebook","telegram","twitter","bluesky","reddit","tiktok"],"default":"whatsapp"},"name":{"type":"string"},"description":{"type":"string"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowNode"}},"edges":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowEdge"}},"entryNodeId":{"type":"string","description":"The trigger node id; derived from the single trigger node if omitted"}}}}}},"responses":{"200":{"description":"Workflow created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"workflow":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"platform":{"type":"string"},"status":{"type":"string"},"nodeCount":{"type":"integer"},"entryNodeId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"x-summary":"The workflow graph is invalid: fix its nodes, edges and platform-specific node settings, then resend.","description":"Invalid graph (duplicate node ids, edges referencing missing nodes, a WhatsApp-only node on another platform, or a WhatsApp interactive list node whose sections carry no rows)"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/workflows/{workflowId}":{"get":{"x-resource-group":"accounts","operationId":"getWorkflow","summary":"Get workflow with graph","description":"Returns a workflow including its full node/edge graph and run stats.","tags":["Workflows"],"parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Workflow details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"workflow":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"platform":{"type":"string"},"accountId":{"type":"string"},"profileId":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused"]},"entryNodeId":{"type":"string"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowNode"}},"edges":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowEdge"}},"totalStarted":{"type":"integer"},"totalCompleted":{"type":"integer"},"totalExited":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"x-resource-group":"accounts","operationId":"updateWorkflow","summary":"Update workflow","description":"Update name, description, the graph, or reassign to a different account.\n\n### Editing the graph\n\nThe graph can be modified in any status, including `active`:\n\n- A run already in progress reloads the saved graph at its next step.\n- A run parked on a node the edit removed completes instead of failing.\n\nEvery graph edit is re-validated, and an invalid graph answers 400 regardless of status.\n\n### Status and account\n\n`status` is not a field of this request; use the activate and pause endpoints.\n\nAccount swaps re-validate the graph against the new platform. For example, moving from WhatsApp to Facebook surfaces a `start_call` node as an error instead of silently saving an unrunnable graph.\n","tags":["Workflows"],"parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowNode"}},"edges":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowEdge"}},"entryNodeId":{"type":["string","null"]},"accountId":{"type":"string","description":"Reassign the workflow to a different `SocialAccount`. Changing this triggers a graph revalidation against the new platform.\n\n`platform` and `profileId` are derived server-side from the new account (the client never sends them directly). The account must belong to the caller's team and be on a workflow-supported platform (whatsapp, instagram, facebook, telegram, twitter, bluesky, reddit, tiktok).\n"}}}}}},"responses":{"200":{"description":"Workflow updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"workflow":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string"},"entryNodeId":{"type":"string"},"nodeCount":{"type":"integer"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"x-summary":"The graph is invalid or the new account is inactive or unsupported: fix the graph or pick another account.","description":"Invalid graph (including a WhatsApp interactive list node whose sections carry no rows), or an account swap to an inactive account or to a platform workflows do not support"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"x-resource-group":"accounts","operationId":"deleteWorkflow","summary":"Delete workflow","description":"Permanently delete a workflow and all of its executions.","tags":["Workflows"],"parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Workflow deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/workflows/{workflowId}/activate":{"post":{"x-resource-group":"accounts","operationId":"activateWorkflow","summary":"Activate workflow","description":"Validate the graph is runnable and set the workflow live. Once active, matching inbound messages start executions. Idempotent.","tags":["Workflows"],"parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Workflow activated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"workflow":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"entryNodeId":{"type":"string"}}}}}}}},"400":{"description":"Incomplete or invalid graph"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/workflows/{workflowId}/pause":{"post":{"x-resource-group":"accounts","operationId":"pauseWorkflow","summary":"Pause workflow","description":"Stop matching new inbound messages. In-flight executions continue to completion. Idempotent.","tags":["Workflows"],"parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Workflow paused","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"workflow":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/workflows/{workflowId}/executions":{"get":{"x-resource-group":"messages","operationId":"listWorkflowExecutions","summary":"List workflow runs","description":"Returns recent executions (runs) with their status, current node, and accumulated variables.","tags":["Workflows"],"parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["running","waiting","completed","exited","failed"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":25}},{"name":"skip","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Executions list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"executions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["running","waiting","completed","exited","failed"]},"currentNodeId":{"type":"string"},"waitingFor":{"type":["object","null"],"properties":{"kind":{"type":"string","enum":["timer","reply"]},"nodeId":{"type":"string"}}},"variables":{"type":"object","additionalProperties":true},"platformIdentifier":{"type":"string"},"conversationId":{"type":["string","null"],"description":"Null only while a comment-triggered run has not sent its private reply yet."},"stepCount":{"type":"integer"},"lastError":{"type":["string","null"]},"resumeAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"skip":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"x-resource-group":"messages","operationId":"triggerWorkflow","summary":"Manually start a workflow run","description":"Kick off a run without waiting for an inbound message (useful for testing). Target an existing conversation by `conversationId`, or (WhatsApp only) a phone number via `to` (a conversation is found or created). `text` seeds the run's `lastMessage` variable. The graph must be runnable.\n","tags":["Workflows"],"parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Provide either `to` (WhatsApp phone) or `conversationId`.","properties":{"to":{"type":"string","description":"Recipient phone (WhatsApp only)"},"conversationId":{"type":"string","description":"An existing conversation to run in (required for non-WhatsApp workflows)"},"text":{"type":"string","description":"Simulated inbound text, seeded as the run's lastMessage variable"}}}}}},"responses":{"200":{"description":"Run started","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"execution":{"type":["object","null"],"properties":{"id":{"type":"string"},"status":{"type":"string"},"currentNodeId":{"type":"string"},"waitingFor":{"type":["object","null"]},"variables":{"type":"object","additionalProperties":true},"conversationId":{"type":"string"}}}}}}}},"400":{"description":"Missing target, invalid graph, or `to` used on a non-WhatsApp workflow"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/workflows/{workflowId}/trigger":{"post":{"x-resource-group":"messages","operationId":"triggerApiCallWorkflow","summary":"Start an API-triggered workflow","description":"Starts a run of an active workflow whose trigger type is `api_call`.\n\nPass exactly one target:\n\n- `conversationId`: a conversation on the workflow's account.\n- `contactId`: resolved to that contact's conversation on the workflow's account.\n- `to` (WhatsApp workflows only): a phone number, whose conversation is found or created.\n\n`variables` are merged over the standard run variables, so each key is available as `{{key}}`.\n","tags":["Workflows"],"parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Exactly one of `conversationId`, `contactId` or `to`.","properties":{"conversationId":{"type":"string","description":"A conversation on the workflow's account"},"contactId":{"type":"string","description":"A contact with a conversation on the workflow's account"},"to":{"type":"string","description":"Recipient phone in E.164 (WhatsApp workflows only)"},"variables":{"type":"object","additionalProperties":true,"description":"Seed variables, merged over the standard run variables"}}}}}},"responses":{"201":{"description":"Run started","content":{"application/json":{"schema":{"type":"object","required":["executionId"],"properties":{"executionId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/workflows/{workflowId}/executions/{executionId}/events":{"get":{"x-resource-group":"messages","operationId":"listWorkflowExecutionEvents","summary":"Get an execution's timeline","description":"Returns the per-step run-log for a single workflow execution: trigger fired, each node visited, edge handles taken, errors, and durations. Backed by Tinybird (90-day retention). Used by the Runs UI drawer to render the timeline.\n","tags":["Workflows"],"parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string"}},{"name":"executionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Timeline events for the execution","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"execution":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["running","waiting","completed","exited","failed"]},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}},"events":{"type":"array","description":"Events in chronological order (oldest first).","items":{"$ref":"#/components/schemas/WorkflowExecutionEvent"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/workflows/{workflowId}/duplicate":{"post":{"x-resource-group":"accounts","operationId":"duplicateWorkflow","summary":"Duplicate a workflow","description":"Create an independent copy of a workflow's graph, name, description, and account binding. The copy is created in `draft` status with fresh execution counters and a new id. Execution history is NOT copied. Useful for branching off a known-good workflow before making experimental edits.\n","tags":["Workflows"],"parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Workflow duplicated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"workflow":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft"]},"platform":{"type":"string"},"accountId":{"type":"string"},"profileId":{"type":"string"},"entryNodeId":{"type":["string","null"]},"nodeCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/workflows/{workflowId}/versions":{"get":{"x-resource-group":"accounts","operationId":"listWorkflowVersions","summary":"List a workflow's version history","description":"Returns the snapshot history. A new version is recorded automatically before every PATCH to `nodes` / `edges` / `entryNodeId`, and explicitly when a previous version is restored. Lightweight list. Call `getWorkflowVersion` for the full snapshot graph.\n","tags":["Workflows"],"parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Versions list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"versions":{"type":"array","description":"Versions in reverse chronological order (newest first).","items":{"type":"object","properties":{"version":{"type":"integer","description":"Monotonically increasing version number"},"name":{"type":"string"},"description":{"type":["string","null"]},"createdBy":{"type":["string","null"],"description":"User id that authored this version"},"createdByEmail":{"type":["string","null"],"description":"Denormalized email so the history UI can render without a join"},"restoredFromVersion":{"type":["integer","null"],"description":"When non-null, this snapshot was created by restoring that version"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/workflows/{workflowId}/versions/{version}":{"get":{"x-resource-group":"accounts","operationId":"getWorkflowVersion","summary":"Get a specific workflow version","description":"Returns the full snapshot for a single historical version, including the graph.","tags":["Workflows"],"parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Version snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"version":{"type":"object","properties":{"version":{"type":"integer"},"name":{"type":"string"},"description":{"type":["string","null"]},"entryNodeId":{"type":["string","null"]},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowNode"}},"edges":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowEdge"}},"platform":{"type":"string"},"accountId":{"type":"string"},"profileId":{"type":"string"},"createdBy":{"type":["string","null"]},"createdByEmail":{"type":["string","null"]},"restoredFromVersion":{"type":["integer","null"]},"createdAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/workflows/{workflowId}/versions/{version}/restore":{"post":{"x-resource-group":"accounts","operationId":"restoreWorkflowVersion","summary":"Restore a workflow version","description":"Replace the current graph with the named version's snapshot.\n\nBefore the swap, the current graph is itself snapshotted as a new version, so a restore is reversible. The workflow must not be `active`: pause it first, then restore.\n\nThe returned workflow carries `restoredFromVersion` so the UI can surface which version was rolled back to.\n","tags":["Workflows"],"parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Workflow restored to the named version","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"workflow":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string"},"entryNodeId":{"type":["string","null"]},"nodeCount":{"type":"integer"},"updatedAt":{"type":"string","format":"date-time"}}},"restoredFromVersion":{"type":"integer"}}}}}},"400":{"description":"Workflow is active, or the named version's graph is invalid for the current platform"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sequences":{"get":{"x-resource-group":"messages","operationId":"listSequences","summary":"List sequences","description":"Returns sequences with enrollment stats. Filter by status, platform, or profile.","tags":["Sequences"],"parameters":[{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Filter by profile. Omit to list across all profiles"},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","active","paused"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"skip","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Sequences list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"sequences":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"platform":{"type":"string"},"accountId":{"type":"string"},"accountName":{"type":"string","description":"Display name of the sending account"},"messagePreview":{"type":"string","description":"First step template name or message text snippet"},"status":{"type":"string","enum":["draft","active","paused"]},"stepsCount":{"type":"integer"},"exitOnReply":{"type":"boolean"},"exitOnUnsubscribe":{"type":"boolean"},"totalEnrolled":{"type":"integer"},"totalCompleted":{"type":"integer"},"totalExited":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"skip":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"x-resource-group":"messages","operationId":"createSequence","summary":"Create sequence","description":"Create a multi-step messaging sequence. Each step has a delay and a message or WhatsApp template.","tags":["Sequences"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","accountId","platform","name"],"properties":{"profileId":{"type":"string"},"accountId":{"type":"string"},"platform":{"type":"string","enum":["instagram","facebook","telegram","twitter","bluesky","reddit","whatsapp","slack"]},"name":{"type":"string"},"description":{"type":"string"},"steps":{"type":"array","items":{"type":"object","required":["order","delayMinutes"],"properties":{"order":{"type":"integer"},"delayMinutes":{"type":"integer"},"message":{"type":"object","properties":{"text":{"type":"string"}}},"template":{"type":"object","properties":{"name":{"type":"string"},"language":{"type":"string"},"variableMapping":{"type":"object","description":"Maps template variable positions to contact fields. Keys are position strings (\"1\", \"2\"), values are objects with field and optional customValue","additionalProperties":{"type":"object","properties":{"field":{"type":"string","enum":["name","phone","email","company","custom"]},"customValue":{"type":"string","description":"Static value when field is \"custom\""}}}}}}}}},"exitOnReply":{"type":"boolean","default":true},"exitOnUnsubscribe":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Sequence created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"sequence":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"platform":{"type":"string"},"status":{"type":"string"},"stepsCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/sequences/{sequenceId}":{"get":{"x-resource-group":"messages","operationId":"getSequence","summary":"Get sequence with steps","description":"Returns a sequence with all its steps and enrollment stats.","tags":["Sequences"],"parameters":[{"name":"sequenceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sequence details with steps","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"sequence":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"platform":{"type":"string"},"accountId":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused"]},"steps":{"type":"array","items":{"type":"object","properties":{"order":{"type":"integer"},"delayMinutes":{"type":"integer"},"message":{"type":"object","properties":{"text":{"type":"string"}}},"template":{"type":"object","properties":{"name":{"type":"string"},"language":{"type":"string"},"variableMapping":{"type":"object"}}}}}},"exitOnReply":{"type":"boolean"},"exitOnUnsubscribe":{"type":"boolean"},"totalEnrolled":{"type":"integer"},"totalCompleted":{"type":"integer"},"totalExited":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"x-resource-group":"messages","operationId":"updateSequence","summary":"Update sequence","description":"Update a sequence's name, steps, or exit conditions. Steps can only be modified while the sequence is draft or paused.","tags":["Sequences"],"parameters":[{"name":"sequenceId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"steps":{"type":"array","description":"Replace the full step list. Only allowed while the sequence is draft or paused.","items":{"type":"object","required":["order","delayMinutes"],"properties":{"order":{"type":"integer"},"delayMinutes":{"type":"integer"},"message":{"type":"object","properties":{"text":{"type":"string"}}},"template":{"type":"object","properties":{"name":{"type":"string"},"language":{"type":"string"},"variableMapping":{"type":"object","additionalProperties":{"type":"object","properties":{"field":{"type":"string","enum":["name","phone","email","company","custom"]},"customValue":{"type":"string"}}}}}}}}},"exitOnReply":{"type":"boolean"},"exitOnUnsubscribe":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Sequence updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"sequence":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string"},"steps":{"type":"array","items":{"type":"object"}},"exitOnReply":{"type":"boolean"},"exitOnUnsubscribe":{"type":"boolean"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"x-resource-group":"messages","operationId":"deleteSequence","summary":"Delete sequence","description":"Permanently delete a sequence. Active enrollments are stopped.","tags":["Sequences"],"parameters":[{"name":"sequenceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sequence deleted"},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sequences/{sequenceId}/activate":{"post":{"x-resource-group":"messages","operationId":"activateSequence","summary":"Activate sequence","description":"Start a draft or paused sequence. The sequence must have at least one step.","tags":["Sequences"],"parameters":[{"name":"sequenceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sequence activated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"sequence":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}}}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sequences/{sequenceId}/pause":{"post":{"x-resource-group":"messages","operationId":"pauseSequence","summary":"Pause sequence","description":"Pause an active sequence. Enrolled contacts stop receiving messages until the sequence is reactivated.","tags":["Sequences"],"parameters":[{"name":"sequenceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sequence paused","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"sequence":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}}}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sequences/{sequenceId}/enroll":{"post":{"x-resource-group":"messages","operationId":"enrollContacts","summary":"Enroll contacts in a sequence","description":"Enroll one or more contacts into a sequence. Contacts already enrolled are skipped.","tags":["Sequences"],"parameters":[{"name":"sequenceId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contactIds"],"properties":{"contactIds":{"type":"array","items":{"type":"string"}},"channelIds":{"type":"array","items":{"type":"string"},"description":"Optional. Auto-detected if not provided."}}}}}},"responses":{"200":{"description":"Enrollment results","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"enrolled":{"type":"integer","description":"Number of contacts successfully enrolled"},"failed":{"type":"integer","description":"Number that failed (already enrolled, or no subscribed channel on the sequence platform)"},"results":{"type":"array","description":"Per-contact outcome","items":{"type":"object","properties":{"contactId":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"string","description":"Present when success is false"}}}}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sequences/{sequenceId}/enroll/{contactId}":{"delete":{"x-resource-group":"messages","operationId":"unenrollContact","summary":"Unenroll contact","description":"Remove a contact from a sequence. No further messages will be sent to this contact.","tags":["Sequences"],"parameters":[{"name":"sequenceId","in":"path","required":true,"schema":{"type":"string"}},{"name":"contactId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Contact unenrolled"},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sequences/{sequenceId}/enrollments":{"get":{"x-resource-group":"messages","operationId":"listSequenceEnrollments","summary":"List enrollments for a sequence","description":"Returns enrolled contacts with their progress, status, and next scheduled step.","tags":["Sequences"],"parameters":[{"name":"sequenceId","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["active","completed","exited","paused"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"skip","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Enrollments list with progress","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"enrollments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"contactId":{"type":"string"},"channelId":{"type":"string"},"platformIdentifier":{"type":"string"},"contactName":{"type":"string"},"currentStepIndex":{"type":"integer"},"status":{"type":"string","enum":["active","completed","exited","paused"]},"exitReason":{"type":["string","null"]},"nextStepAt":{"type":["string","null"],"format":"date-time"},"stepsSent":{"type":"integer"},"lastStepSentAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"skip":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/comment-automations":{"get":{"x-resource-group":"messages","operationId":"listCommentAutomations","tags":["Comment Automations"],"summary":"List comment-to-DM automations","description":"List all comment-to-DM automations for a profile. Returns automations with their stats.","security":[{"bearerAuth":[]}],"parameters":[{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Filter by profile. Omit to list across all profiles"}],"responses":{"200":{"description":"Automations list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"platform":{"type":"string","enum":["instagram","facebook","tiktok","threads","linkedin","youtube"]},"trigger":{"type":"string","enum":["comment","live_comment","story_reply","story_mention"]},"accountId":{"type":"string"},"platformPostId":{"type":"string"},"postTitle":{"type":"string"},"postId":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"matchMode":{"type":"string","enum":["exact","contains","word"],"description":"How a keyword is compared with the comment. 'contains' (default) matches anywhere, even inside another word (keyword 'app' fires on 'happy'). 'word' matches the keyword only as a standalone word. 'exact' requires the whole comment to be exactly the keyword."},"excludeKeywords":{"type":"array","items":{"type":"string"},"description":"Comments containing one of these never trigger the automation, even when a trigger keyword also matches. Compared using the same matchMode."},"typoTolerance":{"type":"boolean","description":"Only with matchMode=word: also fire on close misspellings of a keyword (one edit for 4-7 character keywords, two from 8 up). Keywords shorter than 4 characters are never fuzzy-matched."},"dmMessage":{"type":"string","description":"Instagram and Facebook only. On reply-only platforms (tiktok, threads, linkedin, youtube) every DM-leg field is omitted: dmMessage, dmMessageVariations, buttons, template, quickReplies, dmMedia, publicReplyPolicy, dedupeSameTextHours, actions, audience, followGate, dmDelaySeconds and alsoMatchInDms."},"buttons":{"type":"array","items":{"$ref":"#/components/schemas/DmButton"},"description":"Inline DM buttons (up to 3). Omitted when none are set."},"template":{"$ref":"#/components/schemas/CommentAutomationTemplate"},"commentReply":{"type":"string"},"dmMessageVariations":{"type":"array","items":{"type":"string"},"description":"Alternate DM texts rotated at random with dmMessage. Omitted when none."},"commentReplyVariations":{"type":"array","items":{"type":"string"},"description":"Alternate public replies rotated at random with commentReply. Omitted when none."},"linkTracking":{"type":"boolean","description":"Whether link buttons in the DM are wrapped in a tracked redirect to count clicks."},"clickTag":{"type":"string","description":"Tag applied to a contact when they click a tracked link."},"dmDelaySeconds":{"type":"integer","description":"Seconds waited after the trigger before the DM is sent. Absent when the DM goes out immediately."},"commentReplyDelaySeconds":{"type":"integer","description":"Seconds waited before the public reply is posted. Absent when it follows the DM immediately."},"alsoMatchInDms":{"type":"boolean","description":"Whether these keywords also fire on a plain inbound DM."},"repeatPolicy":{"$ref":"#/components/schemas/CommentAutomationRepeatPolicy"},"dedupeSameTextHours":{"type":"integer","description":"Same-text dedupe window in hours. Omitted when off."},"publicReplyPolicy":{"type":"string","enum":["after_dm","always"]},"actions":{"$ref":"#/components/schemas/CommentAutomationActions"},"quickReplies":{"type":"array","items":{"$ref":"#/components/schemas/CommentAutomationQuickReply"}},"dmMedia":{"$ref":"#/components/schemas/CommentAutomationDmMedia"},"audience":{"$ref":"#/components/schemas/CommentAutomationAudience"},"followGate":{"$ref":"#/components/schemas/CommentAutomationFollowGate"},"isActive":{"type":"boolean"},"stats":{"$ref":"#/components/schemas/CommentAutomationStats"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"400":{"description":"Invalid request"},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}},"post":{"x-resource-group":"messages","operationId":"createCommentAutomation","tags":["Comment Automations"],"summary":"Create comment-to-DM automation","description":"Create a keyword-triggered automation. On Instagram and Facebook, when someone comments a matching keyword (or, with `trigger: story_reply`, replies to your Instagram story with one), they automatically receive a DM.\n\n### Platforms\n\n- `instagram`, `facebook`: the full DM automation (private reply, buttons, product card, audience rules, follow gate) plus the optional public reply.\n- `tiktok`, `threads`, `linkedin`, `youtube`: public reply only (see below).\n- X accounts are refused with a 400 (`platform_not_supported`): X comment polling is off, so an X automation could never fire.\n\n#### Public-reply-only platforms\n\nThese platforms have no private reply to a comment, so the automation answers a matching comment with `commentReply` and nothing else. `commentReply` is required.\n\nThe DM fields are rejected with a 400 naming the field: `dmMessage`, `dmMessageVariations`, `buttons`, `template`, `quickReplies`, `alsoMatchInDms`, `audience`, `followGate`, `dmDelaySeconds`, `commentReplyDelaySeconds`.\n\nHow fast the reply follows the comment:\n\n- TikTok (business accounts only) and Threads: within seconds, since their comments arrive by webhook. Threads keeps the comment poll as a fallback.\n- LinkedIn and YouTube: up to the comment poll interval, 10 minutes on posts from the last 24 hours and longer on older posts.\n\n`repeatPolicy` applies there too: with the default `once`, a person gets one public reply per automation, and their later comments get none.\n\n### Continuing into a workflow\n\nTo continue into a specific workflow after the recipient taps a button, use `{\"type\":\"postback\",\"title\":\"Send it\",\"payload\":\"zernio:workflow:<workflowId>\"}`. The target must be active and belong to the same account and profile. This also works for product-card buttons.\n\n- The tap starts that workflow directly, without matching its keyword or first-message condition.\n- A tap on a workflow that is waiting on `wait_for_reply` in that conversation answers that wait and resumes the run.\n- A tap on a different active workflow starts it and exits the other live runs.\n- Stale or invalid targets still do nothing.\n\nThe initial comment DM alone does not start the workflow: the recipient must tap.\n\n### Triggers (`trigger`)\n\n- `comment` (default): fires on keyword comments on a post or reel.\n- `story_reply`: fires when someone replies to your Instagram story with a keyword, and answers them with a DM. Set `platformPostId` to a story media id to scope to one story, or omit it to match replies to any story.\n- `live_comment` (Instagram only): fires on keyword comments made during one of your Instagram live broadcasts and answers them with a private reply. Meta only accepts the private reply while the broadcast is live.\n- `story_mention` (Instagram only): fires when someone mentions your account in their story, and answers them with a DM. A mention carries no text and Meta does not identify the story, so `keywords` must be empty and `platformPostId` omitted.\n\n`comment` automations never fire on live comments, and `live_comment` ones never fire on post comments.\n\n### How comments are picked up\n\nComments on Instagram and Facebook arrive by webhook. Every 10 minutes Zernio also reads the latest comments and replies back and runs any comment the webhook did not deliver, so a dropped webhook still fires.\n\nThat read covers the bound post, or the 5 newest posts for an account-wide automation, up to 20 Graph reads per account per run. A post not fully read is picked up again on the next run. A comment is answered at most once, whichever path sees it first.\n\n### Targeting (comment trigger)\n\n- Per-post: set `platformPostId` to scope to one specific post (only one active per-post automation is allowed per post).\n- Account-wide (\"any post\"): omit `platformPostId` (and `postId`). The automation evaluates every comment on every post on the account.\n\nYou can stack unlimited account-wide automations, each with its own keyword set, and they all run independently. Per-post automations take priority on their post.\n\n### Audience (`audience`, Instagram only)\n\nRestrict the automation to followers or non-followers, and/or to accounts above a follower count.\n\nInstagram only reveals the follow relationship for people who have messaged the account, so `audience.whenUnknown` decides what happens for everyone else. That includes `verify`, which sends a one-tap confirmation DM (`followGate`) and then delivers the real DM automatically. People we already know follow you skip the tap entirely.\n\nSet `audience.tapToUnlock: true` instead to send that button DM to every commenter and deliver the real DM on the tap with no follow check.\n\n### Matching in DMs\n\nSet `alsoMatchInDms: true` on a `comment` automation to also answer people who send a keyword as a direct message instead of commenting it. Requires at least one keyword.\n\nOne automation then covers both doors, and each door is deduplicated separately: someone who already got the DM from their comment still gets it if they later DM the keyword.\n\n### Link tracking\n\nLinks in the DM's buttons can be click-tracked (`linkTracking`, on by default) and clickers optionally tagged (`clickTag`) for segmentation. Stats returned include delivered, read, and link clicks.\n\n### Personalisation\n\n`{{first_name}}`, `{{name}}` and `{{username}}` in `dmMessage`, `commentReply`, their variations and button titles resolve from the commenter.\n\n- `{{first_name}}`: the first word of the display name.\n- `{{name}}`: the display name.\n- `{{username}}`: the platform username.\n\nWhen the platform gives no display name, `{{first_name}}` and `{{name}}` fall back to the platform username (unless it is all digits). A value still unknown resolves to an empty string and the space before it is dropped.\n\n### Behaviour\n\n- `repeatPolicy`: whether a person can get the DM again.\n- `dedupeSameTextHours`: stops two automations sending the same text to one person.\n- `publicReplyPolicy`: whether the public reply waits for the DM.\n- `actions`: likes or hides the matched comment.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","accountId","name"],"properties":{"profileId":{"type":"string"},"accountId":{"type":"string","description":"Instagram, Facebook, TikTok, Threads, LinkedIn or YouTube account ID. On the last four the automation only posts the public reply. X accounts are refused (400, code platform_not_supported) while X comment polling is off."},"trigger":{"type":"string","enum":["comment","live_comment","story_reply","story_mention"],"default":"comment","description":"What fires the automation:\n\n- 'comment': keyword comment on a post.\n- 'live_comment': keyword comment on an Instagram live broadcast.\n- 'story_reply': keyword reply to an Instagram story. platformPostId is the story media id (omit for any story).\n- 'story_mention': a story mentioning the Instagram account.\n\nEvery trigger but 'comment' is Instagram only; reply-only platforms accept 'comment' only."},"platformPostId":{"type":"string","description":"Platform media/post ID (or story media id when trigger=story_reply). Omit for an account-wide (any-post / any-story) automation."},"postId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio post ID (24 hexadecimal characters); platform IDs return 400. Optional and never required.\n\nUse it INSTEAD of platformPostId to bind a per-post automation to a not-yet-published Zernio post: the automation stays pending and arms itself when that post publishes. For a post already live on the platform, pass platformPostId alone and omit this."},"postTitle":{"type":"string","description":"Post content snippet for display"},"name":{"type":"string","description":"Automation label"},"keywords":{"type":"array","items":{"type":"string"},"description":"Trigger keywords (empty = any comment triggers)"},"matchMode":{"type":"string","enum":["exact","contains","word"],"default":"contains","description":"How a keyword is compared with the comment. 'contains' (default) matches anywhere, even inside another word (keyword 'app' fires on 'happy'). 'word' matches the keyword only as a standalone word. 'exact' requires the whole comment to be exactly the keyword."},"excludeKeywords":{"type":"array","items":{"type":"string"},"description":"Comments containing one of these never trigger the automation, even when a trigger keyword also matches. Compared using the same matchMode."},"typoTolerance":{"type":"boolean","description":"Only with matchMode=word: also fire on close misspellings of a keyword (one edit for 4-7 character keywords, two from 8 up). Keywords shorter than 4 characters are never fuzzy-matched."},"dmMessage":{"type":"string","description":"DM text sent to the commenter. Required on Instagram and Facebook (400 missing_required_field when absent). Rejected on TikTok, Threads, LinkedIn and YouTube, which have no private reply (400 invalid_field_value). Max 640 chars when buttons are set, otherwise ~1000."},"buttons":{"type":"array","maxItems":3,"items":{"$ref":"#/components/schemas/DmButton"},"description":"Optional inline DM buttons (1-3). Phone buttons are Facebook-only. Omit or pass [] for a plain-text DM."},"template":{"allOf":[{"$ref":"#/components/schemas/CommentAutomationTemplate"}],"description":"Optional product card sent INSTEAD of the plain dmMessage bubble. Mutually exclusive with buttons. dmMessage stays required: it is what gets sent the moment the card is cleared."},"commentReply":{"type":"string","description":"Public reply to the comment. Optional on Instagram and Facebook; required on TikTok, Threads, LinkedIn and YouTube, where it is the automation's only action.\n\nOn LinkedIn, mention with `@[Name](urn:li:person:ID)` or `@[Name](urn:li:organization:ID)`, getting the URN from `GET /v1/accounts/{accountId}/linkedin-mentions`. The name must match the person's or Page's LinkedIn name exactly, or the mention renders as plain text. Profile or company URL mentions are not resolved here and are sent as plain text."},"dmMessageVariations":{"type":"array","maxItems":5,"items":{"type":"string"},"description":"Optional alternate DM texts for random rotation. When set, each triggered comment sends one picked at random from [dmMessage, ...dmMessageVariations], so repeat commenters get slightly different DMs (helps avoid identical-message patterns). Up to 5. Buttons are attached to whichever text is picked, not varied."},"commentReplyVariations":{"type":"array","maxItems":5,"items":{"type":"string"},"description":"Optional alternate public replies, rotated at random alongside commentReply (picked independently of the DM). Up to 5.\n\nLinkedIn mentions follow the commentReply rules."},"linkTracking":{"type":"boolean","default":true,"description":"Wrap link buttons in the DM in a tracked redirect so clicks are counted (Link Clicks / CTR). Pass false to send links exactly as written. Defaults to on."},"clickTag":{"type":"string","description":"Optional tag applied to a contact when they click a tracked link (requires linkTracking). Lets you segment clickers for broadcasts/sequences."},"dmDelaySeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Seconds to wait after the trigger before sending the DM. Omit or send 0 to reply immediately (the default). Max 86400 (24h). The trigger is still matched and deduplicated the moment the comment arrives, so a delay only moves when the response is sent."},"commentReplyDelaySeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Seconds to wait before posting the public comment reply. Omit or send 0 to post it right after the DM (the default). The reply never goes out before the DM, so a value below dmDelaySeconds is raised to it. Ignored when trigger=story_reply, which has no public reply."},"alsoMatchInDms":{"type":"boolean","default":false,"description":"Also fire these keywords on a plain inbound DM, so the automation answers people who message the keyword instead of commenting it.\n\n- Requires at least one keyword (an empty list means 'match anything', which would answer every inbound message).\n- Rejected on story_reply automations, which already trigger on DMs.\n- Dedup is per door: a contact who already received the DM from their comment can still receive it from a DM."},"audience":{"$ref":"#/components/schemas/CommentAutomationAudience"},"followGate":{"$ref":"#/components/schemas/CommentAutomationFollowGate"},"repeatPolicy":{"$ref":"#/components/schemas/CommentAutomationRepeatPolicy"},"dedupeSameTextHours":{"type":["integer","null"],"minimum":1,"maximum":8760,"description":"Skip the DM when this recipient already received identical DM text (after personalisation) from this account, from any automation, within this many hours. The skip is logged with status skipped. "},"publicReplyPolicy":{"type":"string","enum":["after_dm","always"],"default":"after_dm","description":"'after_dm' posts commentReply only after a successful DM. 'always' posts it whatever the audience rule, dedupe or DM outcome: the moment a comment matches, or after commentReplyDelaySeconds when set (raised to dmDelaySeconds, so it never precedes the DM attempt)."},"actions":{"$ref":"#/components/schemas/CommentAutomationActions"},"quickReplies":{"type":"array","maxItems":13,"items":{"$ref":"#/components/schemas/CommentAutomationQuickReply"},"description":"Opt-in quick-reply chips on the DM (up to 13). Chips do not render in Message Requests, where a first DM to a cold commenter lands, so prefer buttons for first contact. Mutually exclusive with buttons and template (400). "},"dmMedia":{"oneOf":[{"$ref":"#/components/schemas/CommentAutomationDmMedia"},{"type":"null"}]},"isActive":{"type":"boolean","default":true,"description":"Create the automation paused with false."}}}}}},"responses":{"200":{"description":"Automation created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"automation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"platform":{"type":"string","enum":["instagram","facebook","tiktok","threads","linkedin","youtube"]},"trigger":{"type":"string","enum":["comment","live_comment","story_reply","story_mention"]},"platformPostId":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"matchMode":{"type":"string","enum":["exact","contains","word"],"description":"How a keyword is compared with the comment. 'contains' (default) matches anywhere, even inside another word (keyword 'app' fires on 'happy'). 'word' matches the keyword only as a standalone word. 'exact' requires the whole comment to be exactly the keyword."},"excludeKeywords":{"type":"array","items":{"type":"string"},"description":"Comments containing one of these never trigger the automation, even when a trigger keyword also matches. Compared using the same matchMode."},"typoTolerance":{"type":"boolean","description":"Only with matchMode=word: also fire on close misspellings of a keyword (one edit for 4-7 character keywords, two from 8 up). Keywords shorter than 4 characters are never fuzzy-matched."},"dmMessage":{"type":"string","description":"Omitted on reply-only platforms (tiktok, threads, linkedin, youtube), together with every other DM-leg field."},"buttons":{"type":"array","items":{"$ref":"#/components/schemas/DmButton"},"description":"Inline DM buttons (up to 3). Omitted when none are set."},"template":{"$ref":"#/components/schemas/CommentAutomationTemplate"},"commentReply":{"type":"string"},"dmMessageVariations":{"type":"array","items":{"type":"string"},"description":"Alternate DM texts rotated at random with dmMessage. Omitted when none."},"commentReplyVariations":{"type":"array","items":{"type":"string"},"description":"Alternate public replies rotated at random with commentReply. Omitted when none."},"linkTracking":{"type":"boolean"},"clickTag":{"type":"string"},"dmDelaySeconds":{"type":"integer","description":"Seconds waited after the trigger before the DM is sent. Absent when the DM goes out immediately."},"commentReplyDelaySeconds":{"type":"integer","description":"Seconds waited before the public reply is posted. Absent when it follows the DM immediately."},"audience":{"$ref":"#/components/schemas/CommentAutomationAudience"},"followGate":{"$ref":"#/components/schemas/CommentAutomationFollowGate"},"alsoMatchInDms":{"type":"boolean","description":"Whether these keywords also fire on a plain inbound DM."},"repeatPolicy":{"$ref":"#/components/schemas/CommentAutomationRepeatPolicy"},"dedupeSameTextHours":{"type":"integer","description":"Same-text dedupe window in hours. Omitted when off."},"publicReplyPolicy":{"type":"string","enum":["after_dm","always"]},"actions":{"$ref":"#/components/schemas/CommentAutomationActions"},"quickReplies":{"type":"array","items":{"$ref":"#/components/schemas/CommentAutomationQuickReply"}},"dmMedia":{"$ref":"#/components/schemas/CommentAutomationDmMedia"},"isActive":{"type":"boolean"},"stats":{"$ref":"#/components/schemas/CommentAutomationStats"},"createdAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"x-summary":"The request fails validation: fix the field named in `param`, such as an unsupported platform or unsupported DM fields.","description":"Validation error, including:\n\n- An account on an unsupported platform such as X (code platform_not_supported).\n- A DM field (dmMessage, buttons, template, quickReplies, alsoMatchInDms, audience, followGate, a delay, dmMedia, dedupeSameTextHours, actions) sent for a TikTok, Threads, LinkedIn or YouTube account (code invalid_field_value, param names the field).\n- A missing commentReply on those platforms, or a missing dmMessage on Instagram and Facebook (code missing_required_field).\n- A live_comment, story_reply or story_mention trigger outside Instagram.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"x-summary":"An active per-post automation already exists for this post, so manage the existing one instead of creating another.","description":"Active per-post automation already exists for this platformPostId. Does not apply to account-wide automations."},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/v1/comment-automations/{automationId}":{"get":{"x-resource-group":"messages","operationId":"getCommentAutomation","tags":["Comment Automations"],"summary":"Get automation details","description":"Returns an automation with its configuration, stats, and recent trigger logs.","security":[{"bearerAuth":[]}],"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Automation details with stats and recent trigger logs","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"automation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"platform":{"type":"string","enum":["instagram","facebook","tiktok","threads","linkedin","youtube"]},"trigger":{"type":"string","enum":["comment","live_comment","story_reply","story_mention"]},"accountId":{"type":"string"},"platformPostId":{"type":"string"},"postId":{"type":"string"},"postTitle":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"matchMode":{"type":"string","enum":["exact","contains","word"],"description":"How a keyword is compared with the comment. 'contains' (default) matches anywhere, even inside another word (keyword 'app' fires on 'happy'). 'word' matches the keyword only as a standalone word. 'exact' requires the whole comment to be exactly the keyword."},"excludeKeywords":{"type":"array","items":{"type":"string"},"description":"Comments containing one of these never trigger the automation, even when a trigger keyword also matches. Compared using the same matchMode."},"typoTolerance":{"type":"boolean","description":"Only with matchMode=word: also fire on close misspellings of a keyword (one edit for 4-7 character keywords, two from 8 up). Keywords shorter than 4 characters are never fuzzy-matched."},"dmMessage":{"type":"string","description":"Omitted on reply-only platforms (tiktok, threads, linkedin, youtube), together with every other DM-leg field."},"buttons":{"type":"array","items":{"$ref":"#/components/schemas/DmButton"},"description":"Inline DM buttons (up to 3). Omitted when none are set."},"template":{"$ref":"#/components/schemas/CommentAutomationTemplate"},"commentReply":{"type":"string"},"dmMessageVariations":{"type":"array","items":{"type":"string"},"description":"Alternate DM texts rotated at random with dmMessage. Omitted when none."},"commentReplyVariations":{"type":"array","items":{"type":"string"},"description":"Alternate public replies rotated at random with commentReply. Omitted when none."},"linkTracking":{"type":"boolean"},"clickTag":{"type":"string"},"dmDelaySeconds":{"type":"integer","description":"Seconds waited after the trigger before the DM is sent. Absent when the DM goes out immediately."},"commentReplyDelaySeconds":{"type":"integer","description":"Seconds waited before the public reply is posted. Absent when it follows the DM immediately."},"audience":{"$ref":"#/components/schemas/CommentAutomationAudience"},"followGate":{"$ref":"#/components/schemas/CommentAutomationFollowGate"},"alsoMatchInDms":{"type":"boolean","description":"Whether these keywords also fire on a plain inbound DM."},"repeatPolicy":{"$ref":"#/components/schemas/CommentAutomationRepeatPolicy"},"dedupeSameTextHours":{"type":"integer","description":"Same-text dedupe window in hours. Omitted when off."},"publicReplyPolicy":{"type":"string","enum":["after_dm","always"]},"actions":{"$ref":"#/components/schemas/CommentAutomationActions"},"quickReplies":{"type":"array","items":{"$ref":"#/components/schemas/CommentAutomationQuickReply"}},"dmMedia":{"$ref":"#/components/schemas/CommentAutomationDmMedia"},"isActive":{"type":"boolean"},"stats":{"$ref":"#/components/schemas/CommentAutomationStats"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"logs":{"type":"array","description":"The 20 most recent trigger logs.","items":{"$ref":"#/components/schemas/CommentAutomationLog"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"x-resource-group":"messages","operationId":"updateCommentAutomation","tags":["Comment Automations"],"summary":"Update automation settings","description":"Update an automation's keywords, DM message, inline buttons, comment reply, post binding, or active status.\n\n### Buttons\n\n- Pass `buttons: []` to clear all buttons.\n- When `buttons` is non-empty, `dmMessage` (the new one if you're changing it, otherwise the stored one) must be 640 characters or less.\n\n### Public-reply-only platforms\n\nOn a TikTok, Threads, LinkedIn or YouTube automation (public reply only):\n\n- The DM fields are rejected with a 400 naming the field (`code` invalid_field_value, `param` the field).\n- `commentReply` cannot be cleared.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"trigger":{"type":"string","enum":["comment","live_comment","story_reply","story_mention"],"description":"What fires the automation. Changing it detaches the automation from its bound post or story (a post id and a story id are different objects), unless this same request sets a new binding. Every trigger but 'comment' is Instagram only; 'story_mention' also requires no keywords and no binding."},"keywords":{"type":"array","items":{"type":"string"}},"matchMode":{"type":"string","enum":["exact","contains","word"],"description":"How a keyword is compared with the comment. 'contains' (default) matches anywhere, even inside another word (keyword 'app' fires on 'happy'). 'word' matches the keyword only as a standalone word. 'exact' requires the whole comment to be exactly the keyword."},"excludeKeywords":{"type":"array","items":{"type":"string"},"description":"Comments containing one of these never trigger the automation, even when a trigger keyword also matches. Compared using the same matchMode."},"typoTolerance":{"type":"boolean","description":"Only with matchMode=word: also fire on close misspellings of a keyword (one edit for 4-7 character keywords, two from 8 up). Keywords shorter than 4 characters are never fuzzy-matched."},"platformPostId":{"type":["string","null"],"description":"Re-binds the automation to another post: the platform media/post ID (or story media id when trigger=story_reply). 409 when another active automation already owns the new post.\n\npostId, platformPostId and postTitle move as a unit:\n\n- Sending any of them replaces all three; an omitted one is cleared.\n- All three null (or empty): account-wide (any post / any story).\n- All three omitted: keeps the current binding."},"postId":{"type":["string","null"],"pattern":"^[a-fA-F0-9]{24}$","description":"Zernio post ID (24 hexadecimal characters); platform IDs return 400. Use it INSTEAD of platformPostId to bind to a not-yet-published Zernio post: the automation stays pending and arms itself when that post publishes. Moves as a unit with platformPostId and postTitle (see platformPostId)."},"postTitle":{"type":["string","null"],"description":"Post content snippet for display. Moves as a unit with platformPostId and postId (see platformPostId)."},"dmMessage":{"type":"string"},"buttons":{"type":"array","maxItems":3,"items":{"$ref":"#/components/schemas/DmButton"},"description":"Inline DM buttons (1-3). Pass [] to clear all buttons."},"template":{"oneOf":[{"$ref":"#/components/schemas/CommentAutomationTemplate"},{"type":"null"}],"description":"Product card sent instead of the plain dmMessage bubble. Pass null to clear it and fall back to dmMessage. Mutually exclusive with buttons, including with the buttons already stored on the automation."},"commentReply":{"type":"string","description":"On LinkedIn, mention with `@[Name](urn:li:person:ID)` or `@[Name](urn:li:organization:ID)`, getting the URN from `GET /v1/accounts/{accountId}/linkedin-mentions`. The name must match the person's or Page's LinkedIn name exactly, or the mention renders as plain text. Profile or company URL mentions are not resolved here and are sent as plain text."},"dmMessageVariations":{"type":"array","maxItems":5,"items":{"type":"string"},"description":"Alternate DM texts for random rotation (see create). Pass [] to clear."},"commentReplyVariations":{"type":"array","maxItems":5,"items":{"type":"string"},"description":"Alternate public replies for random rotation. Pass [] to clear.\n\nLinkedIn mentions follow the commentReply rules."},"linkTracking":{"type":"boolean","description":"Wrap link buttons in a tracked redirect to count clicks. Pass false to send links untouched."},"clickTag":{"type":"string","description":"Tag applied to a contact when they click a tracked link (requires linkTracking). Empty string clears it."},"alsoMatchInDms":{"type":"boolean","description":"Also fire these keywords on a plain inbound DM. Enabling it requires the automation to end up with at least one keyword (this request's keywords if you send them, otherwise the stored ones) and is rejected on story_reply automations."},"dmDelaySeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Seconds to wait after the trigger before sending the DM. Send 0 to clear the delay and reply immediately."},"commentReplyDelaySeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Seconds to wait before posting the public comment reply. Send 0 to clear it. The reply never goes out before the DM."},"audience":{"$ref":"#/components/schemas/CommentAutomationAudience"},"followGate":{"$ref":"#/components/schemas/CommentAutomationFollowGate"},"isActive":{"type":"boolean"},"repeatPolicy":{"$ref":"#/components/schemas/CommentAutomationRepeatPolicy"},"dedupeSameTextHours":{"type":["integer","null"],"minimum":1,"maximum":8760,"description":"Skip the DM when this recipient already received identical DM text (after personalisation) from this account, from any automation, within this many hours. The skip is logged with status skipped. Send null to clear."},"publicReplyPolicy":{"type":"string","enum":["after_dm","always"],"description":"'after_dm' posts commentReply only after a successful DM. 'always' posts it whatever the audience rule, dedupe or DM outcome: the moment a comment matches, or after commentReplyDelaySeconds when set (raised to dmDelaySeconds, so it never precedes the DM attempt)."},"actions":{"$ref":"#/components/schemas/CommentAutomationActions"},"quickReplies":{"type":["array","null"],"maxItems":13,"items":{"$ref":"#/components/schemas/CommentAutomationQuickReply"},"description":"Opt-in quick-reply chips on the DM (up to 13). Chips do not render in Message Requests, where a first DM to a cold commenter lands, so prefer buttons for first contact. Mutually exclusive with buttons and template (400). Send null to clear."},"dmMedia":{"oneOf":[{"$ref":"#/components/schemas/CommentAutomationDmMedia"},{"type":"null"}]}}}}}},"responses":{"200":{"description":"Automation updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"automation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"matchMode":{"type":"string","enum":["exact","contains","word"],"description":"How a keyword is compared with the comment. 'contains' (default) matches anywhere, even inside another word (keyword 'app' fires on 'happy'). 'word' matches the keyword only as a standalone word. 'exact' requires the whole comment to be exactly the keyword."},"excludeKeywords":{"type":"array","items":{"type":"string"},"description":"Comments containing one of these never trigger the automation, even when a trigger keyword also matches. Compared using the same matchMode."},"typoTolerance":{"type":"boolean","description":"Only with matchMode=word: also fire on close misspellings of a keyword (one edit for 4-7 character keywords, two from 8 up). Keywords shorter than 4 characters are never fuzzy-matched."},"dmMessage":{"type":"string","description":"Omitted on reply-only platforms (tiktok, threads, linkedin, youtube), together with every other DM-leg field."},"buttons":{"type":"array","items":{"$ref":"#/components/schemas/DmButton"},"description":"Inline DM buttons (up to 3). Omitted when none are set."},"template":{"$ref":"#/components/schemas/CommentAutomationTemplate"},"commentReply":{"type":"string"},"dmMessageVariations":{"type":"array","items":{"type":"string"},"description":"Alternate DM texts rotated at random with dmMessage. Omitted when none."},"commentReplyVariations":{"type":"array","items":{"type":"string"},"description":"Alternate public replies rotated at random with commentReply. Omitted when none."},"audience":{"$ref":"#/components/schemas/CommentAutomationAudience"},"followGate":{"$ref":"#/components/schemas/CommentAutomationFollowGate"},"alsoMatchInDms":{"type":"boolean","description":"Whether these keywords also fire on a plain inbound DM."},"repeatPolicy":{"$ref":"#/components/schemas/CommentAutomationRepeatPolicy"},"dedupeSameTextHours":{"type":"integer","description":"Same-text dedupe window in hours. Omitted when off."},"publicReplyPolicy":{"type":"string","enum":["after_dm","always"]},"actions":{"$ref":"#/components/schemas/CommentAutomationActions"},"quickReplies":{"type":"array","items":{"$ref":"#/components/schemas/CommentAutomationQuickReply"}},"dmMedia":{"$ref":"#/components/schemas/CommentAutomationDmMedia"},"isActive":{"type":"boolean"},"stats":{"$ref":"#/components/schemas/CommentAutomationStats"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"An active automation already exists for the post this request re-binds to"}}},"delete":{"x-resource-group":"messages","operationId":"deleteCommentAutomation","tags":["Comment Automations"],"summary":"Delete automation","description":"Delete an automation. Its trigger logs are kept so tracked links already sent in DMs keep redirecting; they are removed with the account.","security":[{"bearerAuth":[]}],"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Automation deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/comment-automations/{automationId}/logs":{"get":{"x-resource-group":"messages","operationId":"listCommentAutomationLogs","tags":["Comment Automations"],"summary":"List automation logs","description":"Paginated list of every comment that triggered this automation, with send status and commenter info.","security":[{"bearerAuth":[]}],"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","sent","failed","skipped","gated"]},"description":"Filter by result status"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200}},{"name":"skip","in":"query","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"Trigger logs with pagination","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"logs":{"type":"array","items":{"$ref":"#/components/schemas/CommentAutomationLog"}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"skip":{"type":"integer"},"hasMore":{"type":"boolean"}}},"misses":{"type":"object","description":"Comments that reached this automation but matched none of its keywords. These produce no log entry, so this is the only signal that a keyword is catching nothing. Retained for a short window, then dropped.","properties":{"total":{"type":"integer","description":"Number of non-matching comments in the retention window"},"retentionDays":{"type":"integer","description":"How many days of non-matching comments the total covers"},"samples":{"type":"array","description":"A few of the most recent non-matching comments, for diagnosing a keyword setup.","items":{"type":"object","properties":{"commentText":{"type":"string"},"commenterName":{"type":"string"},"excludedBy":{"type":"string","description":"Set when an exclusion keyword vetoed an otherwise matching comment"},"at":{"type":"string","format":"date-time"}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/ads":{"get":{"x-resource-group":"ads","operationId":"listAds","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit","microsoft"],"summary":"List ads","description":"Lists your ads with their performance over a date range, including ads created directly in each platform's ads manager.\n\nReturns a paginated list of ads with metrics computed over an optional date range. Use source=all to include externally-synced ads from platform ad managers.\n\nIf no date range is provided, it defaults to the last 90 days. The date range is capped at 730 days max.\n\n### History\n\nWhen an ad account connects, Zernio imports its last 90 days of metrics, so the metrics hold no data for days before that.\n\nWhen `accountId` or `adAccountId` resolves to a Meta ad account, a range reaching further back answers `202` with `backfillPending: true` and the covered part. The older days (up to 730 days back) are imported in the background; repeat the request until it returns 200.\n\nA request scoped to no Meta account never returns `202`.\n\n### Finding the ad behind a comment\n\nTo find the Zernio ad behind a comment you see in Meta Business Manager:\n\n1. Filter by platformAdId (the Meta ad ID), effectiveObjectStoryId (Facebook), or effectiveInstagramMediaId (Instagram). Those are the post/media the ad's engagement lives on, and are also returned on each ad's `creative` object.\n2. Call GET /v1/ads/{adId}/comments with the returned ad id.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PageParam"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"name":"source","in":"query","schema":{"type":"string","enum":["zernio","all"],"default":"all"},"description":"all (default) = Zernio-created + platform-discovered ads. zernio = restrict to Zernio-created only."},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/AdStatus"}},{"name":"platform","in":"query","schema":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit","microsoft"]}},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Account ID"},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"Platform ad account ID (e.g. act_123 for Meta). Mirrors the same filter on /v1/ads/campaigns and /v1/ads/tree."},{"name":"pageId","in":"query","schema":{"type":"string"},"description":"Meta only: Facebook Page ID. Returns only ads whose creative is backed by this Page (a Meta ad account serves ads for every Page in the Business Manager). Matches each ad's `creative.pageId`; ads with no page signal (rare IG-only creatives) never match. Mirrors the same filter on /v1/ads/campaigns and /v1/ads/tree."},{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Profile ID"},{"name":"campaignId","in":"query","schema":{"type":"string"},"description":"Platform campaign ID (filter ads within a campaign)"},{"name":"adSetId","in":"query","schema":{"type":"string"},"description":"Platform ad set ID (filter ads within an ad set, the /{adset_id}/ads read of an adset-centric dashboard)."},{"name":"platformAdId","in":"query","schema":{"type":"string"},"description":"Meta ad ID. Returns the ad with this platform-side ad ID."},{"name":"effectiveObjectStoryId","in":"query","schema":{"type":"string"},"description":"Facebook `{pageId}_{postId}` of the post the ad's engagement lives on (Meta `effective_object_story_id`). Use to map a Business-Manager-visible post back to the Zernio ad."},{"name":"effectiveInstagramMediaId","in":"query","schema":{"type":"string"},"description":"Instagram media ID of the boosted post (Meta `effective_instagram_media_id`). Use to map a Business-Manager-visible IG post back to the Zernio ad."},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Start of metrics date range (YYYY-MM-DD). Defaults to 90 days ago."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"End of metrics date range (YYYY-MM-DD). Defaults to today. Max 730-day range."}],"responses":{"200":{"description":"Paginated ads","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsListResponse"}}}},"202":{"x-summary":"Historical data is incomplete because the Meta backfill is still pending: retry later for the full history.","description":"Meta only. Historical data is incomplete and backfill remains pending.","headers":{"Retry-After":{"$ref":"#/components/headers/BackfillRetryAfter"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AdsListResponse"},{"type":"object","required":["backfillPending"],"properties":{"backfillPending":{"type":"boolean","description":"Always true on this response. Part of the requested range is still being backfilled; retry until the request returns 200."}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required: legacy plans need the Ads add-on, and usage-based plans include it by default.","description":"Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans."},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"}}}},"/v1/ads/search-terms":{"get":{"x-resource-group":"ads","operationId":"getAdsSearchTerms","tags":["Ad Insights"],"x-platforms":["google"],"summary":"Google Ads search terms report","description":"Shows the actual Google searches that triggered your ads, with spend and results, so you can spot wasted spend and add negative keywords.\n\nEach row is a search query with its matched-keyword status and spend metrics: the raw material for wasted-spend analysis and negative-keyword lists.\n\n- Reads Google's `search_term_view`, cached for the quota window.\n- Defaults to the last 30 days.\n- Rows are ordered by cost, descending.\n- Draws on the shared Google Ads operations budget.\n\nThe response carries `cachedAt` and `stale`, set when a quota-exhausted call falls back to the last-good copy instead of a live read.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Google ads SocialAccount id."},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"Platform ad account ID (Google customer ID, digits only). Defaults to the account's connected customer."},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string"},"description":"Alias of adAccountId, kept for existing callers"},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Defaults to 30 days ago."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"Defaults to today."},{"name":"campaignId","in":"query","schema":{"type":"string"},"description":"Numeric Google campaign id filter."},{"name":"adSetId","in":"query","schema":{"type":"string"},"description":"Platform ad set ID (Google ad group). Same value as adSetId on listAdKeywords and /ad-sets/{adSetId}/assets."},{"name":"adGroupId","in":"query","deprecated":true,"schema":{"type":"string"},"description":"Alias of adSetId, kept for existing callers."},{"name":"pageToken","in":"query","schema":{"type":"string"},"description":"Cursor from paging.nextPageToken of the previous page."}],"responses":{"200":{"description":"Search terms","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"searchTerm":{"type":["string","null"]},"status":{"type":["string","null"],"description":"ADDED / EXCLUDED / ADDED_EXCLUDED / NONE: whether the term is already a keyword or a negative."},"matchType":{"type":["string","null"],"description":"How the term matched (BROAD, PHRASE, EXACT, NEAR_PHRASE, NEAR_EXACT)."},"matchSource":{"type":["string","null"],"description":"What matched the term: ADVERTISER_PROVIDED_KEYWORD (one of your keywords), AI_MAX_BROAD_MATCH or AI_MAX_KEYWORDLESS (AI Max expansion)."},"campaignId":{"type":["string","null"]},"campaignName":{"type":["string","null"]},"adGroupId":{"type":["string","null"]},"adGroupName":{"type":["string","null"]},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"costMicros":{"type":"integer","description":"Cost in micros of the account currency (divide by 1,000,000)."},"conversions":{"type":"number"},"conversionsValue":{"type":"number"}}}},"paging":{"type":"object","properties":{"nextPageToken":{"type":["string","null"],"description":"Null when the last page was returned."}}},"cachedAt":{"type":["string","null"],"format":"date-time","description":"When this data was fetched from Google. Null when it was never served from cache."},"stale":{"type":"boolean","description":"True when Google's daily API quota was exhausted and this is the last successful fetch, not a live read."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget exhausted; retry later."},"501":{"description":"Only available on Google Ads accounts"}}}},"/v1/ads/recommendations":{"get":{"x-resource-group":"ads","operationId":"listGoogleRecommendations","summary":"List Google Ads recommendations","tags":["Ad Campaigns"],"x-platforms":["google"],"security":[{"bearerAuth":[]}],"description":"Lists Google's optimization suggestions for an ad account, with the estimated impact of each.\n\n### What each recommendation includes\n\n- type\n- estimated impact (base vs potential metrics, cost in account currency units)\n- the campaign, ad group or budget they target\n- the type-specific payload Google returns (`details`, in Google's own shape with micros)\n\nFilter by campaignId and types.\n\nCached for 10 minutes and cleared by apply or dismiss. Served stale when Google quota is exhausted.\n","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Google ads SocialAccount id."},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"Google customer id, digits only. Defaults to the connection's only customer."},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string"},"description":"Alias of adAccountId, kept for consistency with other Google endpoints."},{"name":"campaignId","in":"query","schema":{"type":"string","pattern":"^\\d+$"},"description":"Only recommendations targeting this campaign."},{"name":"types","in":"query","schema":{"type":"string"},"description":"Comma-separated Google RecommendationType values, for example CAMPAIGN_BUDGET,KEYWORD,SET_TARGET_CPA."}],"responses":{"200":{"description":"Recommendations.","content":{"application/json":{"schema":{"type":"object","required":["adAccountId","recommendations","cachedAt","stale"],"properties":{"adAccountId":{"type":"string"},"recommendations":{"type":"array","items":{"$ref":"#/components/schemas/GoogleRecommendation"}},"cachedAt":{"type":["string","null"],"format":"date-time"},"stale":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"No Google Ads customer on this connection, or it needs reconnecting."},"429":{"description":"Google quota or the Zernio Google operations burst limit is exhausted."},"501":{"description":"accountId is not a Google Ads connection."}}}},"/v1/ads/recommendations/apply":{"post":{"x-resource-group":"ads","operationId":"applyGoogleRecommendations","summary":"Apply Google Ads recommendations","tags":["Ad Campaigns"],"x-platforms":["google"],"security":[{"bearerAuth":[]}],"description":"Applies Google's optimization suggestions to an ad account, using Google's values or your own; the changes cannot be undone.\n\nApply up to 100 recommendations. This changes the account (budgets, bidding, keywords, assets) and is not reversible or idempotent. Google offers no validate-only mode for it.\n\nItems run in partial-failure mode, so one stale recommendation does not block the rest.\n\n### `parameters`\n\nOptional. It takes exactly one key named for the recommendation type, in Google's ApplyRecommendationOperation shape. For example:\n\n- `campaignBudget: { newBudgetAmountMicros }`\n- `keyword: { matchType, cpcBidMicros }`\n\nOmit it to apply Google's suggested values.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","recommendations"],"properties":{"accountId":{"type":"string","description":"Google ads SocialAccount id."},"adAccountId":{"type":"string","description":"Google customer id, digits only. Required when the connection has several customers."},"recommendations":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["resourceName"],"properties":{"resourceName":{"type":"string","description":"Recommendation resource name from the list, or its id."},"parameters":{"type":"object","description":"One key, such as campaignBudget, keyword, textAd, targetCpaOptIn, targetRoasOptIn, callAsset, calloutAsset, sitelinkAsset, moveUnusedBudget, responsiveSearchAd, responsiveSearchAdAsset, responsiveSearchAdImproveAdStrength, useBroadMatchKeyword, raiseTargetCpa, lowerTargetRoas, setTargetCpa, setTargetRoas, forecastingSetTargetCpa, forecastingSetTargetRoas, leadFormAsset, raiseTargetCpaBidTooLow, raiseTargetCpaPerformanceBidTooLow, lowerTargetRoasPerformanceBidTooLow, calloutExtension, callExtension or sitelinkExtension.","additionalProperties":true}}}}}},"example":{"accountId":"507f1f77bcf86cd799439011","adAccountId":"9122445560","recommendations":[{"resourceName":"customers/9122445560/recommendations/NjgzMzAxODc4NS0yNDEtMTc5MDQ3NTQyNjU5Ni0rMjM1MjA5NjcxNjctMA"},{"resourceName":"customers/9122445560/recommendations/NjgzMzAxODc4NS0yMjgtMTc5MDQyNDE5NjUwNS0rMTU3NjMyNzU3ODk","parameters":{"campaignBudget":{"newBudgetAmountMicros":"150000000"}}}]}}}},"responses":{"200":{"x-summary":"Each recommendation has its own outcome, so check every item because a failed one does not stop the others.","description":"Per-recommendation outcome. A failed item does not stop the others.","content":{"application/json":{"schema":{"type":"object","required":["adAccountId","results"],"properties":{"adAccountId":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/GoogleRecommendationResult"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"No Google Ads customer on this connection, or it needs reconnecting."},"429":{"description":"Google quota or the Zernio Google operations burst limit is exhausted."},"501":{"description":"accountId is not a Google Ads connection."}}}},"/v1/ads/recommendations/dismiss":{"post":{"x-resource-group":"ads","operationId":"dismissGoogleRecommendations","summary":"Dismiss Google Ads recommendations","tags":["Ad Campaigns"],"x-platforms":["google"],"security":[{"bearerAuth":[]}],"description":"Dismisses Google optimization suggestions so Google stops showing them.\n\nDismiss up to 100 recommendations so Google stops suggesting them. Items run in partial-failure mode.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","resourceNames"],"properties":{"accountId":{"type":"string","description":"Google ads SocialAccount id."},"adAccountId":{"type":"string","description":"Google customer id, digits only. Required when the connection has several customers."},"resourceNames":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string"},"description":"Recommendation resource names from the list, or their ids."}}}}}},"responses":{"200":{"x-summary":"Each recommendation has its own outcome, so check every item because a failed one does not stop the others.","description":"Per-recommendation outcome. A failed item does not stop the others.","content":{"application/json":{"schema":{"type":"object","required":["adAccountId","results"],"properties":{"adAccountId":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/GoogleRecommendationResult"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"No Google Ads customer on this connection, or it needs reconnecting."},"429":{"description":"Google quota or the Zernio Google operations burst limit is exhausted."},"501":{"description":"accountId is not a Google Ads connection."}}}},"/v1/ads/bid-strategies":{"get":{"x-resource-group":"ads","operationId":"listBidStrategies","tags":["Ad Campaigns"],"x-platforms":["google"],"summary":"List portfolio bid strategies","description":"Lists a Google Ads account's shared bid strategies with how many campaigns use each and how they performed.\n\nThe bidding strategy report covers type, status, campaign count, clicks, cost, cost per conversion, impressions, average CPC and conversions over the date range (default last 30 days).\n\n### Data source\n\nIt reads Google's `bidding_strategy` resource, cached for the quota window, and draws on the shared Google Ads operations budget.\n\nThe response carries `cachedAt` and `stale`, set when a quota-exhausted call falls back to the last-good copy instead of a live read.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Google ads SocialAccount id."},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"Platform ad account ID (Google customer ID, digits only). Defaults to the account's connected customer."},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string"},"description":"Alias of adAccountId, kept for existing callers"},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Defaults to 30 days ago."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"Defaults to today."}],"responses":{"200":{"description":"Portfolio bid strategies","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"currency":{"type":"string","description":"Account currency code; money fields are in this currency's units."},"strategies":{"type":"array","items":{"$ref":"#/components/schemas/PortfolioBidStrategy"}},"cachedAt":{"type":["string","null"],"format":"date-time","description":"When this data was fetched from Google. Null when it was never served from cache."},"stale":{"type":"boolean","description":"True when Google's daily API quota was exhausted and this is the last successful fetch, not a live read."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget exhausted; retry later."},"501":{"description":"Only available on Google Ads accounts"}}},"post":{"x-resource-group":"ads","operationId":"createBidStrategy","tags":["Ad Campaigns"],"x-platforms":["google"],"summary":"Create portfolio bid strategy","description":"Creates a Google Ads bid strategy that several campaigns can share, such as one target CPA or ROAS.\n\nAttach it to a campaign with `portfolioBidStrategyId` on POST /v1/ads/create, PUT /v1/ads/campaigns/{campaignId}, or PUT /v1/ads/ad-sets/{adSetId}. Attaching a strategy aligned to a shared budget fails there with a 400 (Google's `BIDDING_STRATEGY_AND_BUDGET_MUST_BE_ALIGNED`); this is not retryable.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","name","type"],"properties":{"accountId":{"type":"string","description":"Google ads SocialAccount id."},"adAccountId":{"type":"string","description":"Platform ad account ID (Google customer ID, digits only). Defaults to the account's connected customer."},"customerId":{"type":"string","deprecated":true,"description":"Alias of adAccountId, kept for existing callers"},"name":{"type":"string","minLength":1,"maxLength":255},"type":{"type":"string","enum":["TARGET_CPA","TARGET_ROAS","MAXIMIZE_CONVERSIONS","MAXIMIZE_CONVERSION_VALUE","TARGET_IMPRESSION_SHARE"]},"targetCpa":{"type":"number","exclusiveMinimum":0,"description":"Required when type is TARGET_CPA, in the account's currency units."},"targetRoas":{"type":"number","exclusiveMinimum":0,"description":"Required when type is TARGET_ROAS; a multiplier (2.0 = 2.0x)."},"targetImpressionShare":{"allOf":[{"$ref":"#/components/schemas/GoogleTargetImpressionShare"}],"description":"Required when type is TARGET_IMPRESSION_SHARE, and refused with any other type."}}}}}},"responses":{"201":{"description":"Bid strategy created","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"customerId":{"type":"string"},"id":{"type":"string","description":"Numeric bid strategy id; pass as portfolioBidStrategyId or in the {strategyId} path."},"resourceName":{"type":"string"}}}}}}}},"400":{"x-summary":"The input is invalid or Google rejected the strategy, such as a shared-budget alignment problem.","description":"Invalid input, or Google rejected the strategy (e.g. shared-budget alignment). The message carries Google's error."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"x-summary":"The connection has no Google Ads customer accounts: reconnect Google Ads and retry.","description":"No Google Ads customer accounts on this connection. Reconnect Google Ads."},"429":{"description":"Google Ads operations budget exhausted; retry later."},"501":{"description":"Only available on Google Ads accounts"}}}},"/v1/ads/bid-strategies/{strategyId}":{"patch":{"x-resource-group":"ads","operationId":"updateBidStrategy","tags":["Ad Campaigns"],"x-platforms":["google"],"summary":"Update portfolio bid strategy","description":"Renames a shared Google Ads bid strategy or changes its target CPA or ROAS.\n\nThe strategy's status is output only on Google's side, so it cannot be changed here; remove a strategy in Google Ads.\n\n### When to send `type`\n\n`type` is only needed alongside `targetCpa`/`targetRoas`, to disambiguate the field Google writes to:\n\n- TARGET_CPA and MAXIMIZE_CONVERSIONS both take a target CPA.\n- TARGET_ROAS and MAXIMIZE_CONVERSION_VALUE both take a target ROAS.\n\nThe strategy's family is otherwise immutable once created.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"Numeric Google Ads bid strategy id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"Google ads SocialAccount id."},"adAccountId":{"type":"string","description":"Platform ad account ID (Google customer ID, digits only). Defaults to the account's connected customer."},"customerId":{"type":"string","deprecated":true,"description":"Alias of adAccountId, kept for existing callers"},"name":{"type":"string","minLength":1,"maxLength":255},"type":{"type":"string","enum":["TARGET_CPA","TARGET_ROAS","MAXIMIZE_CONVERSIONS","MAXIMIZE_CONVERSION_VALUE","TARGET_IMPRESSION_SHARE"]},"targetCpa":{"type":"number","exclusiveMinimum":0},"targetRoas":{"type":"number","exclusiveMinimum":0},"targetImpressionShare":{"allOf":[{"$ref":"#/components/schemas/GoogleTargetImpressionShare"}],"description":"Retargets a TARGET_IMPRESSION_SHARE strategy; location, percent and maxCpc are all written."}}}}}},"responses":{"200":{"description":"Bid strategy updated","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"customerId":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget exhausted; retry later."},"501":{"description":"Only available on Google Ads accounts"}}}},"/v1/ads/shared-budgets":{"get":{"x-resource-group":"ads","operationId":"listSharedBudgets","tags":["Ad Campaigns"],"x-platforms":["google"],"summary":"List shared budgets","description":"Lists a Google Ads account's shared budgets and how many campaigns draw from each.\n\nLists the Google Ads customer's shared campaign budgets (`campaign_budget.explicitly_shared`\n= true, not removed), with how many campaigns use each. Move a campaign onto one with\n`sharedBudgetId` on PUT /v1/ads/campaigns/{campaignId}. Google only; other platforms return 501.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Google ads SocialAccount id."},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"Platform ad account ID (Google customer ID, digits only). Defaults to the account's connected customer."}],"responses":{"200":{"description":"Shared budgets","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"budgets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Numeric budget id; pass as sharedBudgetId."},"name":{"type":"string"},"amount":{"type":["number","null"],"description":"In the account's currency units."},"type":{"type":["string","null"],"enum":["daily","lifetime",null]},"deliveryMethod":{"type":["string","null"]},"status":{"type":["string","null"]},"campaignCount":{"type":"integer","description":"campaign_budget.reference_count"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only available on Google Ads accounts"}}},"post":{"x-resource-group":"ads","operationId":"createSharedBudget","tags":["Ad Campaigns"],"x-platforms":["google"],"summary":"Create a shared budget","description":"Creates a daily Google Ads budget that several campaigns can share.\n\nCreates a daily shared campaign budget (`explicitly_shared: true`, standard delivery) that\nseveral campaigns can draw from. A lifetime budget returns 422, like every Google budget.\nGoogle refuses some bidding strategies on a shared budget; that error surfaces when a\ncampaign is moved onto it.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","name","amount"],"properties":{"accountId":{"type":"string","description":"Google ads SocialAccount id."},"adAccountId":{"type":"string","description":"Platform ad account ID (Google customer ID, digits only). Defaults to the account's connected customer."},"name":{"type":"string","minLength":1,"maxLength":255},"amount":{"type":"number","exclusiveMinimum":0,"description":"Daily amount in the account's currency units."},"type":{"type":"string","enum":["daily","lifetime"],"default":"daily","description":"Only daily is accepted (lifetime returns 422)."}}}}}},"responses":{"201":{"description":"Shared budget created","content":{"application/json":{"schema":{"type":"object","properties":{"budget":{"type":"object","properties":{"customerId":{"type":"string"},"id":{"type":"string"},"resourceName":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"description":"Lifetime budget requested."},"501":{"description":"Only available on Google Ads accounts"}}}},"/v1/ads/local-services/leads":{"get":{"x-resource-group":"ads","operationId":"listLocalServicesLeads","tags":["Ad Insights"],"x-platforms":["google"],"summary":"Google Local Services Ads leads","description":"Lists the calls, messages and bookings your Google Local Services Ads generated, newest first.\n\nLeads (phone calls, messages, bookings) are read live from Google's `local_services_lead` resource.\n\n- No persistence: Google is the source of truth, and lead/credit statuses keep changing server-side.\n- Google never returns healthcare-category leads.\n- `WIPED_OUT` leads arrive with contact erased (`contact` is null).\n- Draws on the shared Google Ads operations budget.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Google ads SocialAccount id."},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"Platform ad account ID (Google customer ID, digits only). Defaults to the account's connected customer."},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string"},"description":"Alias of adAccountId, kept for existing callers"},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Leads created at/after this day."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"Leads created at/before this day."},{"name":"leadType","in":"query","schema":{"type":"string","enum":["PHONE_CALL","MESSAGE","BOOKING"]}},{"name":"leadStatus","in":"query","schema":{"type":"string"},"description":"Google LocalServicesLeadStatus enum value (e.g. NEW, BOOKED, WIPED_OUT)."},{"name":"chargedOnly","in":"query","schema":{"type":"boolean"},"description":"true = only leads Google charged for."},{"name":"pageToken","in":"query","schema":{"type":"string"},"description":"Cursor from paging.nextPageToken of the previous page."}],"responses":{"200":{"description":"Local Services leads","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Lead id; pass to /v1/ads/local-services/leads/{leadId}/conversations."},"leadType":{"type":["string","null"],"description":"PHONE_CALL / MESSAGE / BOOKING."},"categoryId":{"type":["string","null"]},"serviceId":{"type":["string","null"]},"contact":{"type":["object","null"],"description":"Null for WIPED_OUT leads (contact erased by Google).","properties":{"consumerName":{"type":["string","null"]},"email":{"type":["string","null"],"description":"Always null: Google Ads API v25 stopped returning the consumer email on Local Services leads."},"phoneNumber":{"type":["string","null"]}}},"status":{"type":["string","null"]},"createdTime":{"type":["string","null"],"description":"Google datetime in the customer's timezone (YYYY-MM-DD HH:MM:SS)."},"locale":{"type":["string","null"]},"charged":{"type":"boolean"},"creditState":{"type":["string","null"]},"creditStateLastUpdate":{"type":["string","null"]}}}},"paging":{"type":"object","properties":{"nextPageToken":{"type":["string","null"],"description":"Null when the last page was returned."}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget exhausted; retry later."},"501":{"description":"Only available on Google Ads accounts"}}}},"/v1/ads/local-services/leads/{leadId}/conversations":{"get":{"x-resource-group":"ads","operationId":"listLocalServicesLeadConversations","tags":["Ad Insights"],"x-platforms":["google"],"summary":"List lead conversations","description":"Shows the calls (with recordings) and messages exchanged with one Google Local Services lead, oldest first.\n\nConversation entries of one Local Services lead: phone calls (duration,\nrecording URL) and messages (text, attachment URLs), oldest first. Read\nlive from `local_services_lead_conversation`, always scoped to a single\nlead. Call-recording URLs require read access on the Google Ads account.\nDraws on the shared Google Ads operations budget.","security":[{"bearerAuth":[]}],"parameters":[{"name":"leadId","in":"path","required":true,"schema":{"type":"string"},"description":"Numeric lead id from /v1/ads/local-services/leads."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Google ads SocialAccount id."},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"Platform ad account ID (Google customer ID, digits only). Defaults to the account's connected customer."},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string"},"description":"Alias of adAccountId, kept for existing callers"},{"name":"pageToken","in":"query","schema":{"type":"string"},"description":"Cursor from paging.nextPageToken of the previous page."}],"responses":{"200":{"description":"Lead conversations","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":["string","null"]},"channel":{"type":["string","null"],"description":"PHONE_CALL / MESSAGE / SMS / EMAIL / WHATSAPP / ADS_API."},"participantType":{"type":["string","null"],"description":"ADVERTISER or CONSUMER."},"eventDateTime":{"type":["string","null"]},"phoneCall":{"type":["object","null"],"description":"Only on PHONE_CALL entries.","properties":{"callDurationMillis":{"type":["integer","null"]},"callRecordingUrl":{"type":["string","null"]}}},"message":{"type":["object","null"],"description":"Only on message-channel entries.","properties":{"text":{"type":["string","null"]},"attachmentUrls":{"type":"array","items":{"type":"string"}}}}}}},"paging":{"type":"object","properties":{"nextPageToken":{"type":["string","null"],"description":"Null when the last page was returned."}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget exhausted; retry later."},"501":{"description":"Only available on Google Ads accounts"}}}},"/v1/ads/keywords":{"get":{"x-resource-group":"ads","operationId":"listAdKeywords","tags":["Ad Campaigns"],"x-platforms":["google"],"summary":"List Search keywords","description":"Lists the keywords and negative keywords in your Google Search ad groups.\n\nReturns the Google Search keyword criteria (positive and negative) synced from connected Google Ads accounts, one row per ad-group keyword.\n\nCampaign-level negative keywords are not included; only ad-group-level criteria are.\n\n### Freshness\n\nKeywords are refreshed about once a day per Google Ads customer (the keyword sweep rides the ads discovery pass on a slower slot). So keywords added on Google can take up to a day to appear.\n\n- A customer synced for the first time is populated on the next discovery pass rather than waiting for its daily slot.\n- Connecting an account or triggering a manual sync refreshes it immediately.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PageParam"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Account ID"},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"Platform ad account ID (Google customer ID). Mirrors the same filter on /v1/ads."},{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Profile ID"},{"name":"campaignId","in":"query","schema":{"type":"string"},"description":"Platform campaign ID"},{"name":"adSetId","in":"query","schema":{"type":"string"},"description":"Platform ad group ID (Google ad group)"},{"name":"status","in":"query","schema":{"type":"string","enum":["active","paused"]},"description":"Keyword criterion status"},{"name":"matchType","in":"query","schema":{"type":"string","enum":["exact","phrase","broad","unknown"]},"description":"Accepted in any case."},{"name":"negative","in":"query","schema":{"type":"boolean"},"description":"true = negative keywords only, false = positive only. Omit for both."},{"name":"search","in":"query","schema":{"type":"string","maxLength":200},"description":"Case-insensitive substring match on the keyword text"}],"responses":{"200":{"description":"Paginated keywords","content":{"application/json":{"schema":{"type":"object","properties":{"keywords":{"type":"array","items":{"$ref":"#/components/schemas/AdKeyword"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required: legacy plans need the Ads add-on, and usage-based plans include it by default.","description":"Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans."}}},"post":{"x-resource-group":"ads","operationId":"addAdKeywords","tags":["Ad Campaigns"],"x-platforms":["google"],"summary":"Add Search ad-group keywords","description":"Adds keywords, or negative keywords, to a Google Search ad group without replacing the ones already there.\n\nAdds one or more keyword criteria to an existing Google Search ad group,\nwithout touching the keywords already there (unlike the whole-set diff on\n`PUT /v1/ads/{adId}`, `keywords`/`negativeKeywords` in `platformSpecificData`,\nwhich replaces the set). Set `negative: true` to add ad-group-level negatives\ninstead of positive keywords.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","adSetId","keywords"],"properties":{"accountId":{"type":"string","description":"Account ID (Google Ads)"},"adSetId":{"type":"string","description":"Google ad group ID to add the keywords to"},"keywords":{"type":"array","minItems":1,"maxItems":1000,"items":{"anyOf":[{"type":"string","description":"Keyword text; defaults to BROAD match"},{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":80},"matchType":{"type":"string","enum":["exact","phrase","broad"]}}}]}},"negative":{"type":"boolean","default":false,"description":"Add as ad-group-level negatives instead of positive keywords"}}}}}},"responses":{"201":{"description":"Keywords added","content":{"application/json":{"schema":{"type":"object","properties":{"keywords":{"type":"array","items":{"$ref":"#/components/schemas/AdKeyword"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only available on Google Ads accounts"}}}},"/v1/ads/keywords/{keywordId}":{"patch":{"x-resource-group":"ads","operationId":"updateAdKeyword","tags":["Ad Campaigns"],"x-platforms":["google"],"summary":"Pause or enable a Search keyword","description":"Pauses or re-enables a single Google Search keyword.\n\nChanges `ad_group_criterion.status` for one keyword criterion (M.140).\nNegative keywords have no status on Google and cannot be paused or enabled.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"keywordId","in":"path","required":true,"schema":{"type":"string"},"description":"Zernio keyword ID (`id`), or Google's native `{adSetId}~{platformCriterionId}` (the tail of `resourceName`, e.g. 1234567890~987654321). A bare criterion id is rejected because it is only unique within its ad group."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["active","paused"]}}}}}},"responses":{"200":{"description":"Keyword updated","content":{"application/json":{"schema":{"type":"object","properties":{"keyword":{"$ref":"#/components/schemas/AdKeyword"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"description":"Negative keywords have no status on Google; they cannot be paused or enabled."}}},"delete":{"x-resource-group":"ads","operationId":"removeAdKeyword","tags":["Ad Campaigns"],"x-platforms":["google"],"summary":"Remove a Search keyword","description":"Removes a single keyword or negative keyword from a Google Search ad group.\n\nRemoves one keyword criterion (positive or negative) from its ad group (M.140).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"keywordId","in":"path","required":true,"schema":{"type":"string"},"description":"Zernio keyword ID (`id`), or Google's native `{adSetId}~{platformCriterionId}` (the tail of `resourceName`, e.g. 1234567890~987654321). A bare criterion id is rejected because it is only unique within its ad group."}],"responses":{"200":{"description":"Keyword removed","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"boolean","description":"Always true on success"},"keywordId":{"type":"string","description":"Zernio keyword ID"},"platformCriterionId":{"type":"string","description":"Google ad_group_criterion.criterion_id"},"resourceName":{"type":"string","description":"Google resource name of the removed criterion"},"campaignId":{"type":"string","description":"Google campaign ID"},"adSetId":{"type":"string","description":"Google ad group ID"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/automations":{"get":{"x-resource-group":"ads","operationId":"listAutomations","tags":["Automations"],"summary":"List automations","description":"Lists the automations on the profiles your key can reach, newest first, across every kind: ad rules, event automations and scheduled automations.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Only automations on this account: the ads connection of an ad rule, or one of the `accountIds` of an event or scheduled automation."},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"Only ad rules checking this platform ad account."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"`nextCursor` from the previous page."}],"responses":{"200":{"description":"Automations","content":{"application/json":{"schema":{"type":"object","required":["automations","nextCursor"],"properties":{"automations":{"type":"array","items":{"$ref":"#/components/schemas/Automation"}},"nextCursor":{"type":["string","null"],"description":"Null on the last page."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"x-resource-group":"ads","operationId":"createAutomation","tags":["Automations"],"summary":"Create an automation","description":"Creates an automation. Its shape picks the kind:\n\n- **Ad rule**: a `schedule` over campaigns, ad sets or ads, with metric `conditions` and ad `steps`. It stays paused unless `status` is `active`; preview it first with `POST /v1/automations/preview`.\n- **Event**: a Zernio event in `trigger.type`, such as `post.failed`, with notify steps. It is on unless `status` is `paused`.\n- **Scheduled**: a `schedule` over a profile's posts, with notify steps and an optional boost. It is on unless `status` is `paused`.\n\nEverything an automation cannot hold is refused at once: the 400 lists every problem with its JSON path in `details.problems`.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationDefinition"},"examples":{"adRule":{"summary":"Pause ads that spend without converting","value":{"name":"Stop losers","status":"active","trigger":{"type":"schedule","every":"1h"},"subjects":{"each":"ad","adAccounts":[{"accountId":"6731a0c2e4b0f1a2b3c4d5e6","adAccountId":"act_1234567890"}]},"conditions":{"all":[{"metric":"spend","window":"last_3d","op":">","value":50},{"metric":"conversions","window":"last_3d","op":"<","value":1}]},"steps":[{"type":"ads.pause"},{"type":"notify.send"}],"limits":{"cooldown":"3d"}}},"event":{"summary":"Tell Slack when an Instagram post fails","value":{"name":"Failed Instagram posts","trigger":{"type":"post.failed","profileId":"6731a0c2e4b0f1a2b3c4d5e7","filter":{"field":"platform","op":"equals","value":"instagram"}},"steps":[{"type":"notify.send","to":[{"accountId":"6731a0c2e4b0f1a2b3c4d5e8","channelId":"C0123456789"}]}],"limits":{"cooldown":"1h"}}},"scheduled":{"summary":"Boost posts that take off","value":{"name":"Boost winners","trigger":{"type":"schedule","every":"1h"},"subjects":{"each":"post","profileId":"6731a0c2e4b0f1a2b3c4d5e7","publishedWithin":"3d"},"filter":{"all":[{"field":"platform","op":"equals","value":"instagram"},{"field":"likes","op":"greater_than","value":500}]},"steps":[{"type":"ads.boost_post","adAccountId":"act_1234567890","budget":50,"days":5,"countries":["US"]}],"limits":{"maxChangesPerDay":3}}}}}}},"responses":{"201":{"description":"Automation created","content":{"application/json":{"schema":{"type":"object","required":["automation"],"properties":{"automation":{"$ref":"#/components/schemas/Automation"}}}}}},"400":{"$ref":"#/components/responses/AutomationInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ad rules only: no ads access (`ads_addon_required`), the ad account is not one the connection selected (`ad_account_not_selected`), or turning it on would raise live spend past the free ads allowance (`ads_allowance_exceeded`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"$ref":"#/components/responses/IdempotencyKeyInFlight"},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"}}}},"/v1/automations/catalog":{"get":{"x-resource-group":"ads","operationId":"getAutomationCatalog","tags":["Automations"],"summary":"Get the automations catalog","description":"What an automation can contain and where each part works, built from the same checks that validate a save, so it never offers what saving refuses.\n\n- `schema`: the JSON Schema of the body of `POST /v1/automations`.\n- `triggers`: every trigger, tagged with its `kind`. Ad rule and scheduled triggers list their intervals; event triggers list each event with its facts.\n- The other sections describe ad rules: per subject (campaign, ad set, ad) its metrics and steps with the platforms that accept them, plus filters, groups, alerts, conditions, limits and approval.\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Catalog","headers":{"Cache-Control":{"schema":{"type":"string","example":"private, max-age=3600"}}},"content":{"application/json":{"schema":{"type":"object","required":["schema","triggers","subjects","filters","groups","alert","conditions","limits","approval"],"properties":{"schema":{"type":"object","description":"JSON Schema of the body of `POST /v1/automations`."},"triggers":{"type":"array","items":{"type":"object","required":["kind","type"],"properties":{"kind":{"type":"string","enum":["ad_rule","event","scheduled"]},"type":{"type":"string","description":"`schedule`, or the Zernio event name.","example":"post.failed"},"label":{"type":"string","description":"Event triggers only."},"subject":{"type":"string","description":"What an event is about, such as `post` or `account`."},"scope":{"type":"object","description":"Which of `profileId` and `accountIds` an event trigger needs."},"facts":{"type":"array","description":"The facts a `filter` can compare, for an event trigger.","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["string","number","boolean"]},"description":{"type":"string"}}}},"subjects":{"type":"array","description":"Scheduled trigger only: what it can check (`post`), with the facts of each.","items":{"type":"object"}},"every":{"type":"array","items":{"type":"string"}},"times":{"type":"object","description":"Ad rule trigger only: the weekly set times it takes."},"filterOperators":{"type":"array","items":{"type":"string"}},"steps":{"type":"array","items":{"type":"string"}},"boost":{"type":"object","description":"Scheduled trigger only: the platforms, goals, most days and most boosts a day of `ads.boost_post`."},"limits":{"type":"array","items":{"type":"string"}}}}},"subjects":{"type":"array","description":"Ad rule subjects.","items":{"type":"object","properties":{"each":{"type":"string","enum":["campaign","adset","ad"]},"platforms":{"type":"array","items":{"type":"string"}},"metrics":{"type":"array","items":{"type":"object","properties":{"metric":{"type":"string"},"platforms":{"type":"array","items":{"type":"string"}}}}},"steps":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"platforms":{"type":"array","items":{"type":"string"}}}}}}}},"filters":{"type":"object","description":"The fields and operators `subjects.filters` takes, and which fields each subject accepts."},"groups":{"type":"object","description":"What `subjects.groups` takes."},"alert":{"type":"object","description":"The most checks `alert.confirmChecks` can ask for."},"conditions":{"type":"object","description":"Condition operators, windows, `compareTo` options and size limits."},"limits":{"type":"array","items":{"type":"string"}},"approval":{"type":"object","description":"Where `approval.request` goes, how many approvers and how long it can wait."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/automations/actions":{"get":{"x-resource-group":"ads","operationId":"listAutomationActions","tags":["Automations"],"summary":"List automation actions","description":"Every change your ad rules made, newest first: what changed, the value before and after, and whether it was applied, skipped or failed. What event and scheduled automations did is in each one's checks.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"automationId","in":"query","schema":{"type":"string"}},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Only actions on this ads connection."},{"name":"type","in":"query","schema":{"type":"string","enum":["ads.pause","ads.activate","ads.set_budget","ads.duplicate","ads.edit_name","ads.set_bid","ads.set_target","ads.reallocate_budget"]},"description":"A change reads as the value it set, so budget changes filter as `ads.set_budget`."},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"`nextCursor` from the previous page."}],"responses":{"200":{"description":"Actions","content":{"application/json":{"schema":{"type":"object","required":["actions","nextCursor"],"properties":{"actions":{"type":"array","items":{"$ref":"#/components/schemas/AutomationAction"}},"nextCursor":{"type":["string","null"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/automations/{automationId}/checks":{"get":{"x-resource-group":"ads","operationId":"listAutomationChecks","tags":["Automations"],"summary":"List an automation's checks","description":"Each time the automation ran, newest first, with what matched and what it did. For an event automation, each check is one event that reached it.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"`nextCursor` from the previous page."}],"responses":{"200":{"description":"Checks","content":{"application/json":{"schema":{"type":"object","required":["checks","nextCursor"],"properties":{"checks":{"type":"array","items":{"$ref":"#/components/schemas/AutomationCheck"}},"nextCursor":{"type":["string","null"],"description":"Null on the last page."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/automations/preview":{"post":{"x-resource-group":"ads","operationId":"previewAutomationDraft","tags":["Automations"],"summary":"Preview an unsaved automation","description":"Shows what an ad rule would do if it ran now, without saving it or changing anything: every object it checks, each condition with its actual value, and the steps a match would run. It refuses what saving would refuse.\n\nEvent and scheduled automations cannot be previewed yet (400, `not_supported`).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"description":"How many subjects to list, matches first. `evaluated` and `matched` always count them all."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationDefinition"}}}},"responses":{"200":{"description":"Preview","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationPreview"}}}},"400":{"$ref":"#/components/responses/AutomationInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AutomationsAdsRequired"}}}},"/v1/automations/{automationId}":{"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"x-resource-group":"ads","operationId":"getAutomation","tags":["Automations"],"summary":"Get an automation","description":"An automation installed from a template also carries `template`.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Automation","content":{"application/json":{"schema":{"type":"object","required":["automation"],"properties":{"automation":{"$ref":"#/components/schemas/Automation"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"x-resource-group":"ads","operationId":"updateAutomation","tags":["Automations"],"summary":"Edit an automation","description":"Replaces the top-level fields you send and keeps the rest: to change one step, send all of `steps`. The result is checked as a whole automation, so problems carry the same paths as on create.\n\nAn automation keeps its kind, and an ad rule stays on its ad account. Send `alert: null` to remove an ad rule's alert.\n\nSend the `version` you read as `If-Match`: if the automation was saved since, the edit is refused with a 409 (`automation_stale`). An edit is also refused with a 409 when another save lands while it is being applied.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"If-Match","in":"header","required":false,"schema":{"type":"string"},"description":"The automation's `version` when you read it."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"status":{"type":"string","enum":["active","paused"]},"trigger":{"$ref":"#/components/schemas/AutomationTrigger"},"subjects":{"oneOf":[{"$ref":"#/components/schemas/AutomationSubjects"},{"$ref":"#/components/schemas/AutomationPostSubjects"}]},"filter":{"$ref":"#/components/schemas/AutomationFactCondition"},"conditions":{"$ref":"#/components/schemas/AdRuleConditions"},"alert":{"oneOf":[{"$ref":"#/components/schemas/AutomationAlert"},{"type":"null"}]},"steps":{"type":"array","minItems":1,"description":"The steps the automation's kind takes.","items":{"oneOf":[{"$ref":"#/components/schemas/AutomationStep"},{"$ref":"#/components/schemas/AutomationBoostStep"}]}},"limits":{"oneOf":[{"$ref":"#/components/schemas/AutomationLimits"},{"$ref":"#/components/schemas/AutomationEventLimits"}]}}}}}},"responses":{"200":{"description":"Automation updated","content":{"application/json":{"schema":{"type":"object","required":["automation"],"properties":{"automation":{"$ref":"#/components/schemas/Automation"}}}}}},"400":{"$ref":"#/components/responses/AutomationInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AutomationsAdsRequired"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The automation was saved after the `version` in `If-Match` (code `automation_stale`). `details.version` is the current one: read it again and resend your edit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"x-resource-group":"ads","operationId":"deleteAutomation","tags":["Automations"],"summary":"Delete an automation","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Automation deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/automations/{automationId}/activate":{"post":{"x-resource-group":"ads","operationId":"activateAutomation","tags":["Automations"],"summary":"Turn an automation on","description":"An ad rule's first check runs right away.","security":[{"bearerAuth":[]}],"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Automation on","content":{"application/json":{"schema":{"type":"object","required":["automation"],"properties":{"automation":{"$ref":"#/components/schemas/Automation"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AutomationsAdsRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/automations/{automationId}/pause":{"post":{"x-resource-group":"ads","operationId":"pauseAutomation","tags":["Automations"],"summary":"Turn an automation off","description":"Pausing never needs ads access.","security":[{"bearerAuth":[]}],"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Automation off","content":{"application/json":{"schema":{"type":"object","required":["automation"],"properties":{"automation":{"$ref":"#/components/schemas/Automation"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/automations/{automationId}/preview":{"post":{"x-resource-group":"ads","operationId":"previewAutomation","tags":["Automations"],"summary":"Preview a saved automation","description":"Shows what an ad rule would do if it ran now. Nothing is changed. Event and scheduled automations cannot be previewed yet (400, `not_supported`).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"description":"How many subjects to list, matches first. `evaluated` and `matched` always count them all."}],"responses":{"200":{"description":"Preview","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationPreview"}}}},"400":{"$ref":"#/components/responses/AutomationInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AutomationsAdsRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/automations/templates":{"get":{"x-resource-group":"ads","operationId":"listAutomationTemplates","tags":["Automations"],"summary":"List automation templates","description":"Lists your team's templates, newest first. Every team member sees the templates any member saved. A team keeps up to 200.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["team"],"default":"team"},"description":"Which templates to list. Only `team` today."}],"responses":{"200":{"description":"Templates","content":{"application/json":{"schema":{"type":"object","required":["templates"],"properties":{"templates":{"type":"array","items":{"$ref":"#/components/schemas/AutomationTemplate"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"x-resource-group":"ads","operationId":"createAutomationTemplate","tags":["Automations"],"summary":"Create an automation template","description":"Saves a reusable setup of one or more automations (up to 20) that your team, or anyone you share it with, can install. Start from your own automations, one of Zernio's templates, a shared template, or definitions sent as they are.\n\nNothing tied to one account is kept. Ad accounts, a trigger's profile and accounts, and alert destinations become `inputs` that each install fills. Campaign ids, id filters, dates and approval steps are dropped.\n\nFrom one of Zernio's templates, each threshold and budget or bid amount also becomes an input, with the template's own value as its default.\n\nA template that would not install is refused: the 400 lists every problem in `details.problems`.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":1000,"default":""}}},{"$ref":"#/components/schemas/AutomationTemplateContent"}]},"examples":{"fromAutomations":{"summary":"From your automations","value":{"name":"Protect spend","description":"Pause losers and alert the team.","from":{"automationIds":["6731a0c2e4b0f1a2b3c4d5e6"]}}},"fromZernio":{"summary":"From a Zernio template","value":{"name":"Stop losers","from":{"templateId":"stop_losers"}}}}}}},"responses":{"201":{"description":"Template created","content":{"application/json":{"schema":{"type":"object","required":["template"],"properties":{"template":{"$ref":"#/components/schemas/AutomationTemplate"}}}}}},"400":{"$ref":"#/components/responses/AutomationInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"An automation in `from.automationIds`, the Zernio template or the shared template was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Your team already keeps 200 templates (code `automation_template_limit`); delete one to save another. Also returned when the same Idempotency-Key is still processing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"}}}},"/v1/automations/templates/{templateId}":{"get":{"x-resource-group":"ads","operationId":"getAutomationTemplate","tags":["Automations"],"summary":"Get an automation template","description":"Returns one of your team's templates, with its inputs and automations.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"templateId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{24}$"},"description":"The template's id."}],"responses":{"200":{"description":"Template","content":{"application/json":{"schema":{"type":"object","required":["template"],"properties":{"template":{"$ref":"#/components/schemas/AutomationTemplate"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No template with this id in your team.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"x-resource-group":"ads","operationId":"updateAutomationTemplate","tags":["Automations"],"summary":"Update an automation template","description":"Renames a template, turns its share link on or off, or replaces its automations. Send at least one field.\n\nRenaming or sharing keeps the `version`. New content (`from` or `automations`) is a new version; automations already installed keep the version they came from.\n\n`visibility: link` turns the share link on (the same link while it stays on) and `visibility: team` revokes it. To copy a shared template, use `POST /v1/automations/templates` instead.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"templateId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{24}$"},"description":"The template's id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":1000},"visibility":{"type":"string","enum":["team","link"]}}},{"$ref":"#/components/schemas/AutomationTemplateContent"}]},"example":{"visibility":"link"}}}},"responses":{"200":{"description":"Template updated","content":{"application/json":{"schema":{"type":"object","required":["template"],"properties":{"template":{"$ref":"#/components/schemas/AutomationTemplate"}}}}}},"400":{"$ref":"#/components/responses/AutomationInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No template with this id in your team, or a source in `from` was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"x-resource-group":"ads","operationId":"deleteAutomationTemplate","tags":["Automations"],"summary":"Delete an automation template","description":"Deletes one of your team's templates and its share link. Automations already installed from it stay.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"templateId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{24}$"},"description":"The template's id."}],"responses":{"200":{"description":"Template deleted","content":{"application/json":{"schema":{"type":"object","required":["deleted"],"properties":{"deleted":{"type":"boolean","description":"Always true."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No template with this id in your team.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/automations/templates/{templateId}/install":{"post":{"x-resource-group":"ads","operationId":"installAutomationTemplate","tags":["Automations"],"summary":"Install an automation template","description":"Creates every automation in the template, with your values in place of its inputs. All or nothing: if one automation fails, the ones already created are removed. New automations stay paused unless `status` is `active`.\n\nTo install on many ad accounts at once, send `targets` (up to 50). Each target is its own install with its own `inputs`, which win over the shared `inputs`. A failed target leaves the others in place, and the response is 207.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"templateId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{24}$"},"description":"The template's id."},{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationTemplateInstallRequest"},"examples":{"one":{"summary":"One ad account","value":{"inputs":{"adAccount":{"accountId":"6731a0c2e4b0f1a2b3c4d5e6","adAccountId":"act_1234567890"}},"status":"active"}},"many":{"summary":"Many ad accounts at once","value":{"inputs":{"alertTo":[{"accountId":"6731a0c2e4b0f1a2b3c4d5e6","to":"alerts@example.com"}]},"targets":[{"inputs":{"adAccount":{"accountId":"6731a0c2e4b0f1a2b3c4d5e6","adAccountId":"act_1234567890"}}},{"inputs":{"adAccount":{"accountId":"6731a0c2e4b0f1a2b3c4d5e7","adAccountId":"act_9876543210"}}}]}}}}}},"responses":{"201":{"description":"Installed. `installation` for one install, `installations` when `targets` was sent and every target installed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationTemplateInstallResponse"}}}},"207":{"description":"Some targets installed and some failed: check each `installations[].status`.","content":{"application/json":{"schema":{"type":"object","required":["installations"],"properties":{"installations":{"type":"array","items":{"$ref":"#/components/schemas/AutomationTemplateTargetResult"}}}}}}},"400":{"description":"The request is invalid, or an input is missing, unknown or of the wrong type: `details.problems` lists each one at its path, such as `inputs.adAccount`.\n\nWhen no target installed, the first target's error is returned with every target's result in `details.installations`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"details":{"$ref":"#/components/schemas/AutomationProblems"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AutomationsAdsRequired"},"404":{"description":"No template with this id in your team.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"$ref":"#/components/responses/IdempotencyKeyInFlight"},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"}}}},"/v1/automations/templates/shared/{shareToken}":{"get":{"x-resource-group":"ads","operationId":"getSharedAutomationTemplate","tags":["Automations"],"summary":"Get a shared automation template","description":"Returns a template shared by link, from any team. Who made it and its install counts in that team are left out, and `share` is null.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"shareToken","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64},"description":"The token from the template's `share.token`."}],"responses":{"200":{"description":"Template","content":{"application/json":{"schema":{"type":"object","required":["template"],"properties":{"template":{"$ref":"#/components/schemas/AutomationTemplate"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No template is shared with this token, or its link was turned off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/automations/templates/shared/{shareToken}/install":{"post":{"x-resource-group":"ads","operationId":"installSharedAutomationTemplate","tags":["Automations"],"summary":"Install a shared automation template","description":"Installs a template shared by link into your account, the same way as your own templates.\n\nTo install on many ad accounts at once, send `targets` (up to 50). Each target is its own install with its own `inputs`, which win over the shared `inputs`. A failed target leaves the others in place, and the response is 207.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"shareToken","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64},"description":"The token from the template's `share.token`."},{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationTemplateInstallRequest"},"examples":{"one":{"summary":"One ad account","value":{"inputs":{"adAccount":{"accountId":"6731a0c2e4b0f1a2b3c4d5e6","adAccountId":"act_1234567890"}},"status":"active"}},"many":{"summary":"Many ad accounts at once","value":{"inputs":{"alertTo":[{"accountId":"6731a0c2e4b0f1a2b3c4d5e6","to":"alerts@example.com"}]},"targets":[{"inputs":{"adAccount":{"accountId":"6731a0c2e4b0f1a2b3c4d5e6","adAccountId":"act_1234567890"}}},{"inputs":{"adAccount":{"accountId":"6731a0c2e4b0f1a2b3c4d5e7","adAccountId":"act_9876543210"}}}]}}}}}},"responses":{"201":{"description":"Installed. `installation` for one install, `installations` when `targets` was sent and every target installed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationTemplateInstallResponse"}}}},"207":{"description":"Some targets installed and some failed: check each `installations[].status`.","content":{"application/json":{"schema":{"type":"object","required":["installations"],"properties":{"installations":{"type":"array","items":{"$ref":"#/components/schemas/AutomationTemplateTargetResult"}}}}}}},"400":{"description":"The request is invalid, or an input is missing, unknown or of the wrong type: `details.problems` lists each one at its path, such as `inputs.adAccount`.\n\nWhen no target installed, the first target's error is returned with every target's result in `details.installations`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"details":{"$ref":"#/components/schemas/AutomationProblems"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AutomationsAdsRequired"},"404":{"description":"No template is shared with this token, or its link was turned off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"$ref":"#/components/responses/IdempotencyKeyInFlight"},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"}}}},"/v1/automations/templates/zernio/{templateId}":{"get":{"x-resource-group":"ads","operationId":"getZernioAutomationTemplate","tags":["Automations"],"summary":"Get a Zernio automation template","description":"Returns one of Zernio's ready-made ad rule templates in the same shape as your own. Each threshold and budget or bid amount is an input with the template's own value as its default, so an install can change it or leave it.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"templateId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":100},"example":"stop_losers","description":"The id of one of Zernio's templates, for example `stop_losers`."}],"responses":{"200":{"description":"Template","content":{"application/json":{"schema":{"type":"object","required":["template"],"properties":{"template":{"$ref":"#/components/schemas/AutomationTemplate"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No Zernio template with this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/automations/templates/zernio/{templateId}/install":{"post":{"x-resource-group":"ads","operationId":"installZernioAutomationTemplate","tags":["Automations"],"summary":"Install a Zernio automation template","description":"Installs one of Zernio's ready-made templates. Leave a value input out to keep the template's default.\n\nTo install on many ad accounts at once, send `targets` (up to 50). Each target is its own install with its own `inputs`, which win over the shared `inputs`. A failed target leaves the others in place, and the response is 207.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"templateId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":100},"example":"stop_losers","description":"The id of one of Zernio's templates, for example `stop_losers`."},{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationTemplateInstallRequest"},"examples":{"one":{"summary":"One ad account","value":{"inputs":{"adAccount":{"accountId":"6731a0c2e4b0f1a2b3c4d5e6","adAccountId":"act_1234567890"}},"status":"active"}},"many":{"summary":"Many ad accounts at once","value":{"inputs":{"alertTo":[{"accountId":"6731a0c2e4b0f1a2b3c4d5e6","to":"alerts@example.com"}]},"targets":[{"inputs":{"adAccount":{"accountId":"6731a0c2e4b0f1a2b3c4d5e6","adAccountId":"act_1234567890"}}},{"inputs":{"adAccount":{"accountId":"6731a0c2e4b0f1a2b3c4d5e7","adAccountId":"act_9876543210"}}}]}}}}}},"responses":{"201":{"description":"Installed. `installation` for one install, `installations` when `targets` was sent and every target installed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationTemplateInstallResponse"}}}},"207":{"description":"Some targets installed and some failed: check each `installations[].status`.","content":{"application/json":{"schema":{"type":"object","required":["installations"],"properties":{"installations":{"type":"array","items":{"$ref":"#/components/schemas/AutomationTemplateTargetResult"}}}}}}},"400":{"description":"The request is invalid, or an input is missing, unknown or of the wrong type: `details.problems` lists each one at its path, such as `inputs.adAccount`.\n\nWhen no target installed, the first target's error is returned with every target's result in `details.installations`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"details":{"$ref":"#/components/schemas/AutomationProblems"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AutomationsAdsRequired"},"404":{"description":"No Zernio template with this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"$ref":"#/components/responses/IdempotencyKeyInFlight"},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"}}}},"/v1/automations/controls":{"get":{"x-resource-group":"ads","operationId":"getAutomationControls","tags":["Automations"],"summary":"Get automation controls","description":"The team's switch for every ad rule, and each ad account's own switch and daily raise limit. Boosting automations do not read them.\n\nEvery team member sees the same controls. `adAccounts` lists each ad account your automations use, plus any ad account that has controls set.\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Controls","content":{"application/json":{"schema":{"type":"object","required":["controls"],"properties":{"controls":{"$ref":"#/components/schemas/AutomationControls"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AutomationsAdsRequired"}}},"patch":{"x-resource-group":"ads","operationId":"updateAutomationControls","tags":["Automations"],"summary":"Turn every ad automation off or on","description":"Turns every ad rule of the team off (`paused: true`) or back on. Each rule keeps its own status, so turning the switch back on resumes exactly the rules that were active.\n\nScheduled automations that boost posts are not stopped by it: pause them one by one.\n\nIt reaches every profile, so only the account owner or a full-access team member can use it. A key limited to some profiles gets 403.\n\nTurning off a switch that is already off keeps its original `pausedAt`.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["paused"],"properties":{"paused":{"type":"boolean","description":"True stops every ad automation of the team; false lets them run again."}}}}}},"responses":{"200":{"description":"The controls after the change","content":{"application/json":{"schema":{"type":"object","required":["controls"],"properties":{"controls":{"$ref":"#/components/schemas/AutomationControls"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Code `insufficient_permissions` when the caller is not the account owner or a full-access team member, or `ads_addon_required` when the account has no ads access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/automations/controls/ad-accounts":{"patch":{"x-resource-group":"ads","operationId":"updateAutomationAdAccountControls","tags":["Automations"],"summary":"Update one ad account's controls","description":"Turns ad rules off or on for one ad account, sets its daily raise limit, or both. Send at least one of `paused` and `dailyRaiseLimit`; fields you leave out keep their value.\n\nThe ad account must be one the connection in `accountId` reaches, as for an automation on it. Controls apply to every ad rule of the team on that ad account.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["accountId","adAccountId"],"properties":{"accountId":{"type":"string","description":"The ads connection that reaches the ad account."},"adAccountId":{"type":"string","minLength":1,"maxLength":64,"description":"The platform's ad account id."},"paused":{"type":"boolean","description":"True stops every automation on this ad account; false lets them run again."},"dailyRaiseLimit":{"type":["number","null"],"minimum":0.01,"maximum":100000000,"description":"The most automations may raise budgets on this ad account in any 24 hours, in the ad account's currency. A raise past it is cut to the room left.\n\nSend null to remove the limit.\n"}}},"example":{"accountId":"6650f1c2a1b2c3d4e5f60718","adAccountId":"act_1234567890","dailyRaiseLimit":500}}}},"responses":{"200":{"description":"The controls after the change","content":{"application/json":{"schema":{"type":"object","required":["controls"],"properties":{"controls":{"$ref":"#/components/schemas/AutomationControls"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Code `ads_addon_required` when the account has no ads access, or `ad_account_not_selected` when the ad account is not among the connection's selected ad accounts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Code `ads_connection_required`: the connection needs reconnecting.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/automations/{automationId}/approvals":{"get":{"x-resource-group":"ads","operationId":"listAutomationApprovals","tags":["Automations"],"summary":"List an automation's approval requests","description":"The requests an automation sent for a person's approval before acting, newest first. Each lists the changes it holds, who may decide it and until when.\n\nOnly automations that ask for approval have requests. Others return 409.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","approved","rejected","expired","cancelled"]},"description":"Only requests in this status."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"How many requests to return. There is no cursor; the newest come first."}],"responses":{"200":{"description":"Approval requests","content":{"application/json":{"schema":{"type":"object","required":["approvals"],"properties":{"approvals":{"type":"array","items":{"$ref":"#/components/schemas/AutomationApproval"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Code `invalid_resource_state`: this automation never waits for approval.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/automations/{automationId}/approvals/{approvalId}":{"get":{"x-resource-group":"ads","operationId":"getAutomationApproval","tags":["Automations"],"summary":"Get an approval request","description":"One approval request with the changes it holds, who may decide it and whether you can.","security":[{"bearerAuth":[]}],"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"approvalId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Approval request","content":{"application/json":{"schema":{"type":"object","required":["approval"],"properties":{"approval":{"$ref":"#/components/schemas/AutomationApproval"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Code `invalid_resource_state`: this automation never waits for approval.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/automations/{automationId}/approvals/{approvalId}/approve":{"post":{"x-resource-group":"ads","operationId":"approveAutomationApproval","tags":["Automations"],"summary":"Approve an approval request","description":"Approves a pending request, so the automation acts on each change it holds. Each change is checked again first, and one that no longer applies is skipped.\n\nOnly the approvers the automation names now can decide, matched by the email of the user behind the API key. A request already decided, expired or cancelled is refused with nothing changed.\n\nEach applied or failed change fires `automation.action.applied` or `automation.action.failed`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"approvalId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationApprovalDecision"}}}},"responses":{"200":{"description":"The request after the decision","content":{"application/json":{"schema":{"type":"object","required":["approval"],"properties":{"approval":{"$ref":"#/components/schemas/AutomationApproval"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Code `insufficient_permissions` when you are not one of the approvers or `token` was sent to someone else, or `ads_addon_required` when the account has no ads access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/AutomationApprovalRefused"}}}},"/v1/automations/{automationId}/approvals/{approvalId}/reject":{"post":{"x-resource-group":"ads","operationId":"rejectAutomationApproval","tags":["Automations"],"summary":"Reject an approval request","description":"Rejects a pending request: every change it holds is skipped and nothing is changed on the ad account.\n\nOnly the approvers the automation names now can decide, matched by the email of the user behind the API key. Rejecting needs no ads access, like pausing.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"approvalId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationApprovalDecision"}}}},"responses":{"200":{"description":"The request after the decision","content":{"application/json":{"schema":{"type":"object","required":["approval"],"properties":{"approval":{"$ref":"#/components/schemas/AutomationApproval"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Code `insufficient_permissions`: you are not one of the approvers, or `token` was sent to someone else.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/AutomationApprovalRefused"}}}},"/v1/automations/backtest":{"post":{"x-resource-group":"ads","operationId":"backtestAutomationDraft","tags":["Automations"],"summary":"Backtest an unsaved automation","description":"Replays an automation over past days on stored daily metrics, without saving it or changing anything. It refuses what saving would refuse.\n\nEach day lists what it would have done. Its own changes carry into later days, but the metrics stay what really happened. `notes` says what the replay could not know.\n\nOnly ad automations can be backtested, on at most 5,000 ads.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/AutomationBacktestDays"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationDefinition"}}}},"responses":{"200":{"description":"Backtest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationBacktest"}}}},"400":{"$ref":"#/components/responses/AutomationInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AutomationsAdsRequired"}}}},"/v1/automations/{automationId}/backtest":{"post":{"x-resource-group":"ads","operationId":"backtestAutomation","tags":["Automations"],"summary":"Backtest a saved automation","description":"What a saved automation would have done over the last `days` days, replayed on stored daily metrics. Nothing is changed.\n\nEach day lists what it would have done. Its own changes carry into later days, but the metrics stay what really happened. `notes` says what the replay could not know.\n\nOnly ad automations can be backtested, on at most 5,000 ads.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/AutomationBacktestDays"}],"responses":{"200":{"description":"Backtest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationBacktest"}}}},"400":{"$ref":"#/components/responses/AutomationInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AutomationsAdsRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/ads/rules":{"get":{"x-resource-group":"ads","operationId":"listAdRules","tags":["Ad Rules"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"List ad rules","description":"Lists the ad rules on the profiles your key can reach, newest first.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Only rules on this ads connection."},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"Only rules watching this platform ad account."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"skip","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Rules","content":{"application/json":{"schema":{"type":"object","required":["rules"],"properties":{"rules":{"type":"array","items":{"$ref":"#/components/schemas/AdRule"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required: legacy plans need the Ads add-on, and usage-based plans include it by default.","description":"Ads access required (code `ads_addon_required`). Legacy plans need the Ads add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"x-resource-group":"ads","operationId":"createAdRule","tags":["Ad Rules"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"Create an ad rule","description":"Creates a rule that checks the campaigns or ad sets of one ad account on a schedule and acts on each one that meets every condition.\n\nRules support Meta, Google, TikTok, LinkedIn, Pinterest, X and Reddit ads connections. Use `POST /v1/ads/rules/{ruleId}/preview` to see what a rule would match before enabling it.\n\n### Evaluation\n\nEach campaign or ad set is evaluated on its own, over the ad account's calendar days, from the metrics Zernio syncs.\n\n### Actions\n\nA rule can notify (the `ad_rule.triggered` webhook), and take at most one of:\n\n- `pause`\n- `activate`\n- `adjust_budget`\n\n### Cooldown\n\nAfter acting on an object, the rule leaves that object alone for `cooldownMinutes`. A rule that pauses, activates or adjusts budgets needs a cooldown at least as long as its schedule.\n\n### How `activate` works\n\n`activate` only reactivates objects a rule paused, never ones you paused yourself, and only once the cooldown has passed since that pause.\n\nIf you reactivate and pause such an object yourself between two runs of a rule, Zernio cannot tell your pause from the rule's, and an `activate` rule may reactivate it.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","accountId","adAccountId","level","conditions","actions"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"accountId":{"type":"string","description":"The ads connection (account ID from `GET /v1/accounts`)."},"adAccountId":{"type":"string","maxLength":64,"description":"Platform ad account ID, from `GET /v1/ads/accounts`."},"level":{"$ref":"#/components/schemas/AdRuleLevel"},"campaignIds":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string"},"description":"Only check these platform campaign IDs (or their ad sets). Leave out to check the whole ad account."},"filters":{"$ref":"#/components/schemas/AdRuleFilters"},"groups":{"$ref":"#/components/schemas/AdRuleGroups"},"lifecycle":{"$ref":"#/components/schemas/AdRuleLifecycle"},"conditions":{"$ref":"#/components/schemas/AdRuleConditions"},"actions":{"$ref":"#/components/schemas/AdRuleActions"},"schedule":{"allOf":[{"$ref":"#/components/schemas/AdRuleSchedule"}],"description":"Leave it out to run every 60 minutes."},"cooldownMinutes":{"type":"integer","minimum":0,"maximum":43200,"default":1440,"description":"How long the rule leaves an object alone after acting on it."},"enabled":{"type":"boolean","default":true}}}}}},"responses":{"201":{"description":"Rule created","content":{"application/json":{"schema":{"type":"object","required":["rule"],"properties":{"rule":{"$ref":"#/components/schemas/AdRule"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is blocked: enable the Ads add-on, select the ad account in the connection, or add a card for budget-raising rules.","description":"Code `ads_addon_required` when the team has no ads access (legacy plans need the Ads add-on), `ad_account_not_selected` when `adAccountId` is not in the connection's selected ad accounts, or `ads_allowance_exceeded` when a rule that reactivates or raises budgets is created for a team past its free live-ads allowance with no payment method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/ads/rules/templates":{"get":{"x-resource-group":"ads","operationId":"listAdRuleTemplates","tags":["Ad Rules"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"List ready-made ad rules","description":"Common rules to start from: stop losers, scale winners, pause ads with no conversions, creative fatigue and spend spike alerts.\n\nEach template is a complete rule body. Add `name`, `accountId` and `adAccountId`, adjust the thresholds to the ad account, and send it to `POST /v1/ads/rules`. Amounts are in the ad account currency. `platforms` lists the networks a template works on, or is null for all of them.\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The templates.","content":{"application/json":{"schema":{"type":"object","required":["templates"],"properties":{"templates":{"type":"array","items":{"type":"object","required":["id","name","description","goal","level","conditions","actions","schedule","cooldownMinutes","platforms"],"properties":{"id":{"type":"string","example":"stop_losers"},"name":{"type":"string"},"description":{"type":"string"},"level":{"$ref":"#/components/schemas/AdRuleLevel"},"conditions":{"$ref":"#/components/schemas/AdRuleConditions"},"actions":{"$ref":"#/components/schemas/AdRuleActions"},"goal":{"type":"string","enum":["protect","scale","schedule","alert"],"description":"What the template is for: stop waste, grow what works, act at set times, or only tell you."},"schedule":{"$ref":"#/components/schemas/AdRuleSchedule"},"cooldownMinutes":{"type":"integer"},"platforms":{"type":["array","null"],"items":{"type":"string"}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/ads/rules/activity":{"get":{"x-resource-group":"ads","operationId":"listAdRuleActivity","tags":["Ad Rules"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"List every change ad rules made","description":"The permanent record of what your rules did: one entry per pause, reactivation or budget change (including skipped and failed attempts), newest first, across all rules of the profiles the key can reach.\nEntries stay after a rule is renamed or deleted; `ruleName` is the rule's name when it acted.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"ruleId","in":"query","schema":{"type":"string"}},{"name":"accountId","in":"query","description":"Only changes of rules on this ads connection.","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string","enum":["pause","activate","adjust_budget","adjust_bid","adjust_target","reallocate_budget","duplicate","edit_name"]}},{"name":"from","in":"query","description":"ISO 8601 date-time, inclusive.","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"ISO 8601 date-time, inclusive.","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"`nextCursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Changes, newest first","content":{"application/json":{"schema":{"type":"object","required":["activity","nextCursor"],"properties":{"activity":{"type":"array","items":{"$ref":"#/components/schemas/AdRuleActivityEntry"}},"nextCursor":{"type":["string","null"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required: legacy plans need the Ads add-on, and usage-based plans include it by default.","description":"Ads access required (code `ads_addon_required`). Legacy plans need the Ads add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/ads/rules/activity/{activityId}/undo":{"post":{"x-resource-group":"ads","operationId":"undoAdRuleActivity","tags":["Ad Rules"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"Undo a change an ad rule made","description":"Puts back a pause, reactivation, budget or bid change, or name tag a rule applied, as a new change recorded in the activity feed. The rule's cooldown then covers the object.\n\nIt is refused (409 `invalid_resource_state`) when the change was not applied, was already undone, is a copy, or when the object changed since: delivering again after a pause, paused again after a reactivation, or on another budget, bid or name.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"activityId","in":"path","required":true,"description":"The `id` of an entry from `GET /v1/ads/rules/activity`.","schema":{"type":"string","pattern":"^[0-9a-f]{24}-[0-9]+$"}}],"responses":{"200":{"description":"The undo was recorded and attempted","content":{"application/json":{"schema":{"type":"object","required":["undo"],"properties":{"undo":{"type":"object","required":["id","status","reason"],"properties":{"id":{"type":"string","description":"The undo's own activity entry id."},"status":{"type":"string","enum":["applied","skipped","unknown"],"description":"`skipped` when the object was already as it was before the change."},"reason":{"type":["string","null"]}}}}}}}},"202":{"description":"The platform did not answer; `undo.status` is `unknown` and the rule's next run reads back whether it went through."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads access required (code `ads_addon_required`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such activity entry in the profiles the key can reach.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The change cannot be undone (code `invalid_resource_state`); `error` says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The platform refused the undo (code `platform_api_error`). The change can be undone again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/ads/rules/{ruleId}":{"parameters":[{"name":"ruleId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"x-resource-group":"ads","operationId":"getAdRule","tags":["Ad Rules"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"Get an ad rule","description":"Returns one ad rule.\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Rule","content":{"application/json":{"schema":{"type":"object","required":["rule"],"properties":{"rule":{"$ref":"#/components/schemas/AdRule"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required: legacy plans need the Ads add-on, and usage-based plans include it by default.","description":"Ads access required (code `ads_addon_required`). Legacy plans need the Ads add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"x-resource-group":"ads","operationId":"updateAdRule","tags":["Ad Rules"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"Update an ad rule","description":"Changes any field of a rule except its connection and ad account. Send `campaignIds: null` to\ncheck the whole ad account again. Changing the schedule, or enabling a disabled rule, moves the\nnext run; re-sending `enabled: true` on an enabled rule does not.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"level":{"$ref":"#/components/schemas/AdRuleLevel"},"campaignIds":{"type":["array","null"],"minItems":1,"maxItems":100,"items":{"type":"string"}},"filters":{"$ref":"#/components/schemas/AdRuleFilters"},"groups":{"allOf":[{"$ref":"#/components/schemas/AdRuleGroups"}],"description":"Null removes the groups; each campaign is then judged on its own."},"lifecycle":{"oneOf":[{"$ref":"#/components/schemas/AdRuleLifecycle"},{"type":"null"}],"description":"Null removes it; every matching run then acts and notifies again."},"conditions":{"$ref":"#/components/schemas/AdRuleConditions"},"actions":{"$ref":"#/components/schemas/AdRuleActions"},"schedule":{"$ref":"#/components/schemas/AdRuleSchedule"},"cooldownMinutes":{"type":"integer","minimum":0,"maximum":43200},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Rule updated","content":{"application/json":{"schema":{"type":"object","required":["rule"],"properties":{"rule":{"$ref":"#/components/schemas/AdRule"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing, or the free live ads allowance is used up and enabling this rule needs a payment method.","description":"Code `ads_addon_required` when the team has no ads access, or `ads_allowance_exceeded` when the change enables a rule that reactivates or raises budgets for a team past its free live-ads allowance with no payment method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"x-resource-group":"ads","operationId":"deleteAdRule","tags":["Ad Rules"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"Delete an ad rule","description":"Deletes a rule and its run history. Changes the rule already made on the platform stay.\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Rule deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required: legacy plans need the Ads add-on, and usage-based plans include it by default.","description":"Ads access required (code `ads_addon_required`). Legacy plans need the Ads add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/ads/rules/{ruleId}/preview":{"post":{"x-resource-group":"ads","operationId":"previewAdRule","tags":["Ad Rules"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"Preview an ad rule","description":"Evaluates a rule against current metrics and returns what it would match right now, without\nacting on anything, sending a webhook or starting a cooldown. Works on disabled rules.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"ruleId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Evaluation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdRuleEvaluation"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required: legacy plans need the Ads add-on, and usage-based plans include it by default.","description":"Ads access required (code `ads_addon_required`). Legacy plans need the Ads add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/ads/rules/{ruleId}/alerts":{"get":{"x-resource-group":"ads","operationId":"listAdRuleAlerts","tags":["Ad Rules"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"List a rule's alerts","description":"The alert episodes of a rule with a `lifecycle`, newest first. `pending` alerts are confirming, `open` ones were acted on, `resolved` ones ended, with `resolvedReason` saying why. Resolved alerts are kept 90 days.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"ruleId","in":"path","required":true,"schema":{"type":"string"}},{"name":"state","in":"query","schema":{"type":"string","enum":["pending","open","resolved"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"`nextCursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Alerts, newest first","content":{"application/json":{"schema":{"type":"object","required":["alerts","nextCursor"],"properties":{"alerts":{"type":"array","items":{"type":"object","required":["id","objectId","state","severity","consecutiveMatches","openedAt","lastMatchedAt","resolvedAt","resolvedReason"],"properties":{"id":{"type":"string"},"objectId":{"type":"string","description":"Platform campaign, ad set or ad ID."},"state":{"type":"string","enum":["pending","open","resolved"]},"severity":{"type":["string","null"],"enum":["warning","critical",null]},"consecutiveMatches":{"type":"integer"},"openedAt":{"type":["string","null"],"format":"date-time"},"lastMatchedAt":{"type":"string","format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"resolvedReason":{"type":["string","null"],"enum":["condition_cleared","action_applied","not_evaluated","automation_changed","automation_off",null]}}}},"nextCursor":{"type":["string","null"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Rule not found in the profiles the key can reach.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/ads/rules/{ruleId}/runs":{"get":{"x-resource-group":"ads","operationId":"listAdRuleRuns","tags":["Ad Rules"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"List an ad rule's runs","description":"Lists a rule's scheduled runs, newest first: what each run evaluated, matched and did.\nRuns that changed something (or tried to) are kept permanently, also after the rule is deleted; runs that changed nothing are dropped after about 31 days.\nFor every change across all rules, use `GET /v1/ads/rules/activity`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"ruleId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"skip","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Runs","content":{"application/json":{"schema":{"type":"object","required":["runs"],"properties":{"runs":{"type":"array","items":{"$ref":"#/components/schemas/AdRuleRun"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required: legacy plans need the Ads add-on, and usage-based plans include it by default.","description":"Ads access required (code `ads_addon_required`). Legacy plans need the Ads add-on; included by default on usage-based plans.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/ads/campaign-results":{"post":{"x-resource-group":"ads","operationId":"uploadCampaignResults","tags":["Ad Campaign Results"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"Upload your results per campaign","description":"Sends your own daily numbers per campaign (qualified leads, sales, revenue...) so rules and reports can use them next to spend.\n\nName each row's campaign by `campaignId`, `utmCampaign` or `campaignName`. Rows are matched in the background: the `202` returns an `uploadId`, and `Location` points to `GET /v1/ads/campaign-results/uploads/{uploadId}`.\n\nRe-sending a day replaces it. Send an `Idempotency-Key` to retry safely. Limits per team: 60 requests and 20,000 rows per hour, 512 KB per request.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":255},"description":"A retry with the same key and body replays the first response instead of uploading twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rows"],"properties":{"rows":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"object","required":["date","values"],"description":"Exactly one of `campaignId`, `utmCampaign` or `campaignName`.","properties":{"date":{"type":"string","format":"date","description":"The day, at most 400 days ago."},"campaignId":{"type":"string","description":"The platform campaign id."},"utmCampaign":{"type":"string","description":"The `utm_campaign` value on the campaign's ads."},"campaignName":{"type":"string","description":"The campaign's name, matched case-insensitively."},"adAccountId":{"type":"string","description":"Platform ad account id. Narrows matching to one ad account."},"values":{"type":"object","description":"Metric key (snake_case, up to 40 characters) to a non-negative number. 1 to 20 per row.","additionalProperties":{"type":"number","minimum":0},"example":{"qualified_leads":14,"sales":2,"revenue":7800}}}}}}}}}},"responses":{"202":{"description":"Queued for matching.","headers":{"Location":{"schema":{"type":"string"},"description":"The upload, to check how its rows were matched."}},"content":{"application/json":{"schema":{"type":"object","required":["uploadId","rows","status"],"properties":{"uploadId":{"type":"string"},"rows":{"type":"integer"},"status":{"type":"string","enum":["queued"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Code `ads_addon_required` when the team has no ads access."},"409":{"x-summary":"The same Idempotency-Key is still being processed: retry shortly.","description":"The same `Idempotency-Key` is still being processed. Retry shortly."},"413":{"description":"Code `payload_too_large`: the body is over 512 KB."},"422":{"description":"The `Idempotency-Key` was used with a different body."},"429":{"$ref":"#/components/responses/RateLimited"}}},"get":{"x-resource-group":"ads","operationId":"listCampaignResults","tags":["Ad Campaign Results"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"List your results per campaign","description":"Your results summed per campaign over a date range, one entry per campaign with every metric it has, for the ad accounts your key can see. Each day counts its newest uploaded value only, plus the events sent to `POST /v1/events` that are tied to the campaign (`sales`, `revenue`, `leads`, `qualified_leads`).\n\nPaginated by campaign: pass `nextCursor` back as `cursor` until it is null.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"fromDate","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"toDate","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Inclusive. At most 400 days after `fromDate`."},{"name":"campaignIds","in":"query","schema":{"type":"string"},"description":"Comma-separated platform campaign ids, at most 500. Omit for all campaigns."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"description":"Campaigns per page."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"`nextCursor` from the previous page."}],"responses":{"200":{"description":"One page of campaigns.","content":{"application/json":{"schema":{"type":"object","required":["fromDate","toDate","campaigns","nextCursor"],"properties":{"fromDate":{"type":"string","format":"date"},"toDate":{"type":"string","format":"date"},"campaigns":{"type":"array","items":{"type":"object","required":["platform","adAccountId","campaignId","values"],"properties":{"platform":{"type":"string"},"adAccountId":{"type":"string"},"campaignId":{"type":"string"},"values":{"type":"object","additionalProperties":{"type":"number"}}}}},"nextCursor":{"type":["string","null"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/ads/campaign-results/uploads/{uploadId}":{"get":{"x-resource-group":"ads","operationId":"getCampaignResultsUpload","tags":["Ad Campaign Results"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"Check a results upload","description":"How an upload was matched: rows matched and unmatched, and up to 100 unmatched rows with why (`no_campaign` or `ambiguous`).\n\n`status` turns `done` once every row is processed, usually within seconds. Uploads are kept for 30 days.\n\nA `failed` upload says why in `failureReason`. Send it again: re-sending a day replaces it, so nothing is counted twice.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"uploadId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The upload's outcome.","content":{"application/json":{"schema":{"type":"object","required":["uploadId","status","source","rowsReceived","rowsMatched","rowsUnmatched","unmatched","failureReason","createdAt","completedAt"],"properties":{"uploadId":{"type":"string"},"status":{"type":"string","enum":["queued","done","failed"]},"source":{"type":"string","enum":["api","csv","hubspot"]},"rowsReceived":{"type":"integer"},"rowsMatched":{"type":"integer"},"rowsUnmatched":{"type":"integer"},"unmatched":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","description":"The row's position in the request."},"campaign":{"type":"string","description":"The campaign id, UTM or name the row gave."},"reason":{"type":"string","enum":["no_campaign","ambiguous"]}}}},"failureReason":{"type":["string","null"],"enum":["queue_unavailable","processing_failed",null],"description":"Set when `status` is `failed`. `queue_unavailable`: the upload could not be queued. `processing_failed`: its rows could not be stored after several retries. Both are on our side."},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/ads/campaign-results/totals":{"get":{"x-resource-group":"ads","operationId":"getCampaignResultsTotals","tags":["Ad Campaign Results"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"Get your results totals","description":"Each metric you send summed over a date range across every campaign of the ad accounts your key can see, or of the ones you name. Each day counts its newest uploaded value only, plus the events sent to `POST /v1/events` that are tied to a campaign.\n\nFormulas are not computed here, since they also read the platform's numbers: apply one to these totals and the account's spend for the same range, or read it per campaign from `GET /v1/ads/tree?results=true`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"fromDate","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"toDate","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Inclusive. At most 400 days after `fromDate`."},{"name":"adAccountIds","in":"query","schema":{"type":"string"},"description":"Comma-separated platform ad account ids, at most 100. Omit for every ad account your key can see."}],"responses":{"200":{"description":"The totals by metric key.","content":{"application/json":{"schema":{"type":"object","required":["fromDate","toDate","totals"],"properties":{"fromDate":{"type":"string","format":"date"},"toDate":{"type":"string","format":"date"},"totals":{"type":"object","additionalProperties":{"type":"number"},"example":{"qualified_leads":140,"sales":23,"revenue":41200}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/ads/campaign-results/metrics":{"get":{"x-resource-group":"ads","operationId":"listCampaignResultMetrics","tags":["Ad Campaign Results"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"List your result metrics","description":"The metric keys your team has sent, with their label and kind, then the formulas: your own and the built-in ones (`cac_percent`, `cost_per_sale`, `cost_per_qualified_lead`, `lead_to_sale`). A new key appears as a `count` labelled from the key; name it, or define a formula, with `PUT /v1/ads/campaign-results/metrics/{key}`.\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The metrics.","content":{"application/json":{"schema":{"type":"object","required":["metrics"],"properties":{"metrics":{"type":"array","items":{"$ref":"#/components/schemas/CampaignResultMetric"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/ads/campaign-results/metrics/{key}":{"put":{"x-resource-group":"ads","operationId":"setCampaignResultMetric","tags":["Ad Campaign Results"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"Name a result metric or define a formula","description":"Sets a metric key's label and kind: `count` for things you count (leads, sales), `money` with its currency (revenue), `percent` or `ratio`.\n\nSend `formula` to make it a computed metric: `+ - * /` and parentheses over `spend`, `impressions`, `clicks`, `conversions`, `purchase_value` and the metrics you send, at most 200 characters. A formula cannot read another formula.\n\nIt is computed per campaign over the summed values of the range, and has no value when an input is missing or a division is by zero.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["label","kind"],"properties":{"label":{"type":"string","maxLength":80,"example":"Qualified leads"},"kind":{"type":"string","enum":["count","money","percent","ratio"]},"currency":{"type":["string","null"],"description":"ISO 4217, money metrics only.","example":"EUR"},"formula":{"type":["string","null"],"maxLength":200,"description":"Makes it a computed metric. Null or absent for a number you send.","example":"spend / sales"}}}}}},"responses":{"200":{"description":"The metric.","content":{"application/json":{"schema":{"type":"object","required":["metric"],"properties":{"metric":{"$ref":"#/components/schemas/CampaignResultMetric"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/ads/campaigns":{"get":{"x-resource-group":"ads","operationId":"listAdCampaigns","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit","microsoft"],"summary":"List campaigns","description":"Lists your campaigns with spend, impressions and clicks summed across their ads, plus each campaign's status and budget.\n\nCampaigns are virtual aggregations over ad documents grouped by platform campaign ID. Metrics (spend, impressions, clicks, etc.) are summed across all ads in each campaign.\n\nCampaign status is derived from child ad statuses: active > pending_review > paused > error > completed > cancelled > rejected.\n\nGoogle campaign budgets include amountMicros, explicitlyShared, resourceName and deliveryMethod after the next successful sync. This endpoint does not fetch Google live.\n\n**Status freshness.** `status`, `configuredStatus`, `platformStatus`, `platformAdSetStatus` and `platformCampaignStatus` are the values Zernio last stored.\n\nBackground sync refreshes them, typically within 15 to 60 minutes (Google up to about 3 hours), and ended or long-paused objects may be refreshed less often.\n\nZernio's own status writes re-read the switches they change. A change made in the platform's own ads manager therefore shows up here only after the next sync.\n\n### Live status reads\n\nControllers that act on a switch should pass `live=true`. It reads the switches from the platform now, stores them, and returns `statusReadAt` (null when the read failed and the stored values were returned).\n\n- `live=true` needs `limit` of 20 or less.\n- Each returned campaign's own switch (`platformCampaignStatus`) is read live.\n- Live reads cover TikTok, Meta, Google, OpenAI and Reddit.\n- The rolled-up `status` is not re-derived by a live read.\n\n**Budgets here are SYNCED**, never read live, including with `live=true`. To read the current budgets (and status) of every campaign and ad set of a Meta ad account live in one call, for example as a pre-write spend gate, use GET /v1/ads/accounts/live.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"includeEmpty","in":"query","required":false,"schema":{"type":"boolean"},"description":"Meta only. Set true to also list campaigns with ZERO ads, with `adCount: 0` and zeroed metrics.\n\nCampaign reads aggregate over ad documents, so such campaigns are normally invisible. The two-step create (campaign, then ads via `existingCampaignId`) leaves one behind whenever Meta rejects the ad step.\n\nRequires `accountId` and `adAccountId`, since an empty campaign has no ad row to resolve a token or ad account from.\n"},{"$ref":"#/components/parameters/PageParam"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"source","in":"query","schema":{"type":"string","enum":["zernio","all"],"default":"all"},"description":"`all` (default) returns both Zernio-created ads and those discovered from the platform's ad manager. Matches the web UI's default view. Pass `zernio` to restrict to isExternal=false only. Status is NOT filtered by default; use the `status` param for that."},{"name":"platform","in":"query","schema":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit","microsoft"]}},{"name":"status","in":"query","schema":{"anyOf":[{"$ref":"#/components/schemas/AdStatus"},{"type":"string","enum":["not_deleted"]}]},"description":"Filter by derived campaign status (post-aggregation). `not_deleted` keeps every status except `cancelled`."},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"Platform ad account ID (e.g. act_123 for Meta)"},{"name":"campaignId","in":"query","schema":{"type":"string"},"description":"Platform campaign ID (the `platformCampaignId` on each returned campaign). Returns only that campaign, or an empty list when it is not visible to the caller. Mirrors the same filter on /v1/ads and /v1/ads/tree."},{"name":"pageId","in":"query","schema":{"type":"string"},"description":"Meta only: Facebook Page ID. Campaigns have no Page of their own, so this keeps campaigns having at least one ad backed by this Page, with adCount and metrics computed over those ads only. Mirrors the same filter on /v1/ads and /v1/ads/tree."},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Account ID"},{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Profile ID"},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Start of metrics date range (YYYY-MM-DD, inclusive). Defaults to 90 days ago when both date params are omitted."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"End of metrics date range (YYYY-MM-DD, inclusive). Defaults to today. Max 730-day range."},{"name":"hasDelivery","in":"query","schema":{"type":"boolean"},"description":"Return only campaigns that delivered between `fromDate` and `toDate`: spend above zero, or impressions served at zero spend.\n\nUnlike `status`, which reads a campaign's CURRENT state, this filters on what happened inside the window. It filters the campaign set itself, so `pagination.total` counts only matching campaigns. Mirrors the same filter on /v1/ads/tree."},{"name":"minSpend","in":"query","schema":{"type":"number","minimum":0},"description":"Return only campaigns whose spend between `fromDate` and `toDate` reaches this amount, in each campaign's OWN currency (the `currency` field on the campaign). Implies `hasDelivery`; `minSpend=0` applies no filter. Mirrors the same filter on /v1/ads/tree."},{"$ref":"#/components/parameters/LiveStatusRead"}],"responses":{"200":{"description":"Paginated campaigns","content":{"application/json":{"schema":{"type":"object","properties":{"campaigns":{"type":"array","items":{"$ref":"#/components/schemas/AdCampaign"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"example":{"campaigns":[{"platformCampaignId":"123456789","platform":"google","campaignName":"Search campaign","budget":{"amount":5,"amountMicros":"5000000","type":"daily","explicitlyShared":false,"resourceName":"customers/9122445560/campaignBudgets/1234567890","deliveryMethod":"STANDARD"}}],"pagination":{"page":1,"limit":20,"total":1,"pages":1}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required: legacy plans need the Ads add-on, and usage-based plans include it by default.","description":"Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"}}},"post":{"x-resource-group":"ads","operationId":"createAdCampaign","tags":["Ad Campaigns"],"x-platforms":["meta","google","linkedin","tiktok","x","pinterest","openai","reddit"],"summary":"Create a standalone campaign","description":"Creates an empty campaign, paused, so you can add ad sets and ads to it afterwards.\n\nCreates a campaign WITHOUT its first ad set / ad, on the platform of the given `accountId`. Ad sets join it later via `existingCampaignId` on the create endpoints.\n\nCreated `PAUSED` (TikTok `DISABLE`) unless `status: ACTIVE` where the platform supports it.\n\n**Idempotency:** send an `Idempotency-Key` header to make retries safe.\n\n### Field support\n\n- `specialAdCategories`: Meta-only (400 elsewhere).\n- `bidStrategy`: Meta and Google (400 elsewhere). Google also accepts `portfolioBidStrategyId` instead.\n- Budget: Google, X and OpenAI require one (422 without one). OpenAI accepts daily or lifetime, Google only `budgetType: daily`.\n\n### Platform notes\n\n- Meta: a budget here is campaign-level (CBO) by definition. Omit it for ABO (each ad set carries its own budget).\n- OpenAI: `goal` sets the campaign objective, and `conversions` needs an active standard conversion event on the account.\n- Reddit: see below.\n- LinkedIn: creates the campaign GROUP (our campaign level) and rejects a budget, which lives on the campaign (ad set) level there. It comes back `status: DRAFT`.\n\n### Reddit\n\n`goal` is one of traffic, awareness, conversions, video_views or lead_generation (422 otherwise). The budget is optional.\n\n- With a budget, the campaign uses Reddit's campaign budget optimization and carries the pixel (see `promotedObject`, which then needs `customEventType` for `conversions`). The budget is daily or lifetime; a lifetime budget needs `endDate` (400 otherwise).\n- `startDate` / `endDate` set the campaign's schedule and need that campaign budget (400 without one).\n- Without a budget, each ad set carries its own budget and dates.\n","security":[{"bearerAuth":[]}],"parameters":[{"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.\n\n- Same key + same body: replays the original response.\n- Same key + different body: 422.\n- Key still processing: 409.\n\nOnly 2xx responses are stored, so a request that failed with a 4xx can be retried with a corrected body under the SAME key.\n"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","adAccountId","name","goal"],"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id (posting or ads variant); its platform decides where the campaign is created."},"adAccountId":{"type":"string","description":"Platform ad account id (Meta act_<n>, Google customer id, LinkedIn account id, ...)."},"name":{"type":"string","maxLength":255},"goal":{"type":"string","enum":["engagement","traffic","awareness","video_views","lead_generation","lead_conversion","job_applicants","conversions","app_promotion","catalog_sales","page_likes","page_visits"],"description":"Mapped to the ODAX objective (same mapping as POST /v1/ads/create)."},"isSkadnetworkAttribution":{"type":"boolean","description":"Meta app promotion only. Immutable campaign flag. Set true for iOS 14+ SKAdNetwork campaigns and supply promotedObject.applicationId plus promotedObject.objectStoreUrl. The campaign receives promotedObject only when this flag is true. Cannot be changed on an existing campaign."},"promotedObject":{"$ref":"#/components/schemas/AdPromotedObject"},"buyingType":{"type":"string","enum":["AUCTION","RESERVED"],"description":"Every platform buys at auction by default, so this only needs sending on Meta, and only to choose RESERVED. `AUCTION` is accepted on every platform and changes nothing. `RESERVED` (Reach & Frequency) is Meta-only and is rejected with a 400 elsewhere. SKAdNetwork app promotion requires AUCTION."},"validateOnly":{"type":"boolean","description":"Meta and ChatGPT (OpenAI). Runs campaign validation without creating or persisting a campaign; Idempotency-Key storage is bypassed. Returns HTTP 200 with validateOnly true and status VALIDATED.\n\nOpenAI has no dry-run, so Zernio checks the budget, goal and conversion event itself. `true` on any other platform returns 501 `feature_not_available` (same as POST /v1/ads/create); `false` is ignored.\n"},"specialAdCategories":{"type":"array","items":{"type":"string","enum":["HOUSING","EMPLOYMENT","CREDIT","ISSUES_ELECTIONS_POLITICS","FINANCIAL_PRODUCTS_SERVICES","ONLINE_GAMBLING_AND_GAMING"]}},"budgetAmount":{"type":"number","description":"Campaign-level (CBO) budget in WHOLE currency units (USD: 50 = $50.00), NOT cents. Meta's own Marketing API takes this same number in minor units, so it is an easy and expensive mix-up. Requires budgetType."},"budgetType":{"type":"string","enum":["daily","lifetime"]},"status":{"type":"string","enum":["ACTIVE","PAUSED"],"default":"PAUSED"},"startDate":{"type":"string","format":"date-time","description":"Reddit only (400 elsewhere). Campaign start (ISO 8601); a value without an offset is read in the ad account time zone. Requires a campaign budget (`budgetAmount` + `budgetType`, 400 otherwise). Defaults to now."},"endDate":{"type":"string","format":"date-time","description":"Reddit only (400 elsewhere). Campaign end (ISO 8601); a value without an offset is read in the ad account time zone. Requires a campaign budget (400 otherwise), and is required for `budgetType: lifetime`."},"locationTargetingType":{"allOf":[{"$ref":"#/components/schemas/GoogleLocationTargetingType"}],"description":"Google only (400 elsewhere). Written on the new campaign."},"bidStrategy":{"type":"string","enum":["LOWEST_COST_WITHOUT_CAP","LOWEST_COST_WITH_BID_CAP","COST_CAP","LOWEST_COST_WITH_MIN_ROAS"],"description":"Campaign bid strategy.\n\n**Meta** stores `bid_strategy` alongside the budget, so this REQUIRES `budgetAmount` + `budgetType` on the same request (400 without a campaign budget).\n\nA campaign carrying a strategy without its `bid_amount` makes every ad set under it fail (code 100, subcode 1815857), so that state is rejected up front. To bid at ad-set level, set the strategy there instead.\n\n**Google:**\n\n- LOWEST_COST_WITHOUT_CAP = Maximize Conversions\n- COST_CAP + bidAmount = Target CPA\n- LOWEST_COST_WITH_MIN_ROAS + roasAverageFloor = Target ROAS\n- LOWEST_COST_WITH_BID_CAP + bidAmount = Maximize Clicks with a CPC ceiling\n- portfolioBidStrategyId attaches a portfolio strategy instead.\n"},"bidAmount":{"type":"number","description":"Whole currency units (USD: 5 = $5.00). Required for LOWEST_COST_WITH_BID_CAP and COST_CAP; ignored otherwise.\n\n- Meta: validated here but NOT stored, since the campaign object only has bid_strategy. The amount takes effect once an ad set joins this campaign (existingCampaignId on POST /v1/ads/create) and supplies its own bidAmount there.\n- Google: stored directly on the campaign's bidding strategy."},"roasAverageFloor":{"type":"number","description":"Decimal ROAS multiplier (2.0 = 2.0x). Required for LOWEST_COST_WITH_MIN_ROAS."},"portfolioBidStrategyId":{"type":"string","pattern":"^\\d+$","description":"Google only. Attach an existing portfolio bid strategy (numeric id from GET /v1/ads/bid-strategies) to the new campaign instead of a standard one. Exclusive with bidStrategy."},"targetImpressionShare":{"allOf":[{"$ref":"#/components/schemas/GoogleTargetImpressionShare"}],"description":"Google Search only. Target impression share bidding. Exclusive with bidStrategy, portfolioBidStrategyId and manualCpc; bidAmount is refused alongside it (the ceiling is maxCpc)."},"manualCpc":{"$ref":"#/components/schemas/GoogleManualCpc"},"networkSettings":{"$ref":"#/components/schemas/GoogleNetworkSettings"}}},"example":{"accountId":"69fc524892b3d8e85f893e73","adAccountId":"act_757082720485182","name":"iOS app campaign","goal":"app_promotion","isSkadnetworkAttribution":true,"promotedObject":{"applicationId":"123456789","objectStoreUrl":"https://apps.apple.com/us/app/id123456789"},"buyingType":"AUCTION","status":"PAUSED","validateOnly":true}}}},"responses":{"200":{"description":"Campaign validation passed without creating a campaign.","content":{"application/json":{"schema":{"type":"object","properties":{"validateOnly":{"type":"boolean","description":"Always true."},"adAccountId":{"type":"string"},"campaignId":{"type":"string","const":"","description":"Empty because no campaign was created."},"objective":{"type":"string"},"status":{"type":"string","const":"VALIDATED"}}},"example":{"validateOnly":true,"adAccountId":"act_757082720485182","campaignId":"","objective":"OUTCOME_APP_PROMOTION","status":"VALIDATED"}}}},"201":{"description":"Campaign created","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"campaignId":{"type":"string","description":"Platform id of the new campaign"},"objective":{"type":"string","description":"Resolved ODAX objective (e.g. OUTCOME_SALES)."},"status":{"type":"string","enum":["ACTIVE","PAUSED"]}}}}}},"400":{"description":"Invalid input, or Meta rejected the create"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/MetaAdAccountWriteLimited"},"501":{"x-summary":"The request needs a feature this platform lacks, such as validateOnly outside Meta or campaign-only creation: remove that option.","description":"`validateOnly: true` outside Meta, or campaign-only creation on a platform that does not support it. Carries code `feature_not_available`."}}}},"/v1/ads/campaigns/{campaignId}/status":{"put":{"x-resource-group":"ads","operationId":"updateAdCampaignStatus","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","openai","reddit","microsoft"],"summary":"Pause or resume a campaign","description":"Pauses or resumes a campaign, leaving the on/off switches of its ad sets and ads as they are.\n\nIt writes the campaign's own on/off switch and nothing else, on every platform: Meta, TikTok, Google, LinkedIn campaign group, Pinterest, X, ChatGPT (OpenAI).\n\nIts ad sets and ads keep their own switches:\n\n- Pausing stops their delivery through the campaign.\n- Resuming lets each of them deliver again only if its own switch is on.\n\nAn ad set or ad you paused individually stays paused. Resume it with PUT /v1/ads/ad-sets/{adSetId}/status or PUT /v1/ads/{adId}/status. See the Status model in the Ad Campaigns tag.\n\n### Live read, then write\n\nThe campaign's switch is read from the platform first.\n\n- **Already in the requested state:** nothing is written (`updated: 0`, `skipped: 1`, with the reason).\n- **Otherwise:** the switch is written (`updated: 1`), read back and stored. The delivery status of the ads under it (up to 20) is re-read and stored, so an immediate GET returns what the platform now reports.\n\nWhen the campaign delivers in the requested state but some of its ads are stored in the other state, those ads are re-read and stored (up to 20, at most once every 10 minutes per campaign).\n\nAn example is ads switched on in the platform's own UI and still stored `paused`.\n\nA stored switch never skips a write, and when the platform cannot be read the write always goes out.\n\nOn Meta the check reads the campaign's own `status`, so a delivery status such as `IN_PROCESS` or `WITH_ISSUES` does not force a write.\n\n### Retrying\n\nRetrying the same request is safe: when the first call already switched the campaign, the live read answers `skipped: 1` and nothing is written twice. A call that timed out on your side may still have completed, so retry it instead of assuming it failed.\n\nThese errors fail the same way on every retry until something changes:\n\n- `401` `reconnect_required`: the platform no longer accepts the connection's token (on Meta, code 190: expired, revoked, password changed or security checkpoint). Reconnect the account, then retry.\n- `422` `ad_account_unusable`: the ad account's status does not allow edits. Resolve it in the platform, then retry.\n- `400` `platform_api_error` saying the campaign was deleted or archived (Meta subcodes 1487566 and 3858863): there is nothing left to switch.\n\nA Meta code 190 with subcode 464 means Meta considers the Facebook user unconfirmed. It answers `400` `platform_api_error` and retrying does not clear it: the user must log in to facebook.com and complete what Meta asks (usually confirming their email or phone), then retry.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform campaign ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status","platform"],"properties":{"status":{"type":"string","enum":["active","paused"]},"platform":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit","microsoft"]}}}}}},"responses":{"200":{"description":"Campaign status updated","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","paused"],"description":"The campaign's delivery status derived from its switch as read back (`paused` when the switch is off). Echoes the request when the platform could not be read."},"platformCampaignStatus":{"type":["string","null"],"description":"The campaign's own switch as read back from the platform, in the raw platform vocabulary: Meta effective_status, TikTok ENABLE / DISABLE, Google ENABLED / PAUSED, ChatGPT (OpenAI) status, Reddit configured_status.\n\nNull when the platform could not be read, which is always the case on Pinterest, LinkedIn and X (no single-campaign read)."},"statusReadAt":{"type":["string","null"],"format":"date-time","description":"When the switch was read back. Null when it could not be read."},"updated":{"type":"integer","enum":[0,1],"description":"1 when the campaign's switch was written."},"skipped":{"type":"integer","enum":[0,1],"description":"1 when a live read showed the campaign already in the requested state, so nothing was written."},"skippedReasons":{"type":"array","items":{"type":"string"},"description":"Why the write was skipped, for example \"Campaign already switched off\"."}}}}}},"400":{"description":"Invalid input, campaign spans multiple accounts, or the platform refused the write (`platform_api_error`, see Retrying above)"},"401":{"x-summary":"The API key is invalid or the platform rejected the connection token: send a valid key or reconnect the account, then retry.","description":"Missing or invalid API key (`missing_credentials` / `invalid_credentials`), or the platform no longer accepts the connection's token (`reconnect_required`): reconnect the account, then retry."},"403":{"x-summary":"The free live ads limit is reached without a card, or the account is not selected: add a card or select it.","description":"Forbidden. Two codes:\n\n- `ads_allowance_exceeded`: the team has no payment method on file and has reached the 500 free live ads. Add a card to resume.\n- `ad_account_not_selected`: the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"description":"No ads found for this campaign"},"422":{"x-summary":"The ad account's status does not allow edits: resolve it on the platform, then retry.","description":"`ad_account_unusable`: the ad account's status does not allow edits. Resolve it in the platform, then retry."}}}},"/v1/ads/campaigns/{campaignId}/ad-schedule":{"get":{"x-resource-group":"ads","operationId":"getCampaignAdSchedule","tags":["Ad Campaigns"],"x-platforms":["google"],"summary":"Read a campaign's ad schedule (dayparting)","description":"Shows the days and hours a Google campaign runs and its bid adjustments, optionally with performance by day and hour.\n\nThe windows a Google campaign serves in, with the bid modifier on each, plus the\ncriterion ids Google minted for them.\n\nAn EMPTY `schedule` is meaningful and is not a failed lookup: Google has no\n\"all day\" criterion, so a campaign with no ad schedule serves around the clock.\n`servesAroundTheClock` states that explicitly.\n\nSet `includePerformance=true` to also get delivery split by day of week and by hour,\nwhich is the evidence for deciding what the schedule should be. It is one extra\nGoogle call segmented by both dimensions at once, so the two views always agree.\n\nGoogle Ads only. The response carries `cachedAt` and `stale`, set when a\nquota-exhausted call falls back to the last-good copy instead of a live read.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Numeric Google platform campaign id."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["google"]},"description":"Disambiguates the campaign id when the connection spans platforms."},{"name":"includePerformance","in":"query","required":false,"schema":{"type":"boolean"},"description":"Also return delivery by day of week and by hour. Costs one extra Google call."},{"name":"windowDays","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":90,"default":30},"description":"Trailing window for the performance split. Ignored when fromDate and toDate are both given."},{"name":"fromDate","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Start of an explicit performance range (YYYY-MM-DD). Use together with toDate."},{"name":"toDate","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"End of an explicit performance range (YYYY-MM-DD). Must be on or after fromDate."}],"responses":{"200":{"description":"The campaign's ad schedule","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"schedule":{"type":"array","items":{"$ref":"#/components/schemas/AdScheduleWindow"}},"servesAroundTheClock":{"type":"boolean","description":"True when the campaign carries no ad schedule at all, so it can serve at any time."},"cachedAt":{"type":["string","null"],"format":"date-time"},"stale":{"type":"boolean","description":"True when a quota-exhausted read served the last-good copy."},"performance":{"type":"object","description":"Only present when includePerformance=true.","properties":{"windowDays":{"type":["integer","null"],"description":"The trailing window used, or null when an explicit fromDate/toDate range was given."},"byDayOfWeek":{"type":"array","description":"One entry per day that delivered, Monday first.","items":{"type":"object","properties":{"dayOfWeek":{"type":"string","enum":["MONDAY","TUESDAY","WEDNESDAY","THURSDAY","FRIDAY","SATURDAY","SUNDAY"]},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"cost":{"type":"number","description":"Account currency, not USD-normalized."},"conversions":{"type":"number"}}}},"byHour":{"type":"array","description":"One entry per hour that delivered, 0-23 in the account time zone.","items":{"type":"object","properties":{"hour":{"type":"integer","minimum":0,"maximum":23},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"cost":{"type":"number","description":"Account currency, not USD-normalized."},"conversions":{"type":"number"}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required: legacy plans need the Ads add-on, and usage-based plans include it by default.","description":"Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"501":{"description":"Not a Google Ads campaign: ad schedules are a Google criterion."}}},"put":{"x-resource-group":"ads","operationId":"updateCampaignAdSchedule","tags":["Ad Campaigns"],"x-platforms":["google"],"summary":"Replace a campaign's ad schedule (dayparting)","description":"Replaces the days and hours a Google campaign runs, or clears them so it serves around the clock.\n\nThis is a REPLACE, not a merge: windows you leave out stop serving. Send `schedule: []` to clear dayparting, which returns the campaign to serving around the clock.\n\n### Rules\n\nGoogle rules are enforced here, so you get a named field instead of a criterion error:\n\n- at most 6 windows per day\n- a window must end after it starts\n- windows on the same day may not overlap\n- `endHour` 24 is midnight and cannot carry minutes\n- minutes are quarter-hours only (0, 15, 30, 45)\n- `bidModifier` is 0.1-10.0. Google's 0 means \"off\" for devices only, so a window is switched off by leaving it out.\n\nWindows are half-open (Google is exclusive of the end minute), so 09:00-12:00 and 12:00-17:00 on the same day are adjacent and both valid.\n\n### How it is applied\n\nGoogle cannot edit an ad schedule in place (every AdScheduleInfo field is prohibited on update). So this removes the live criteria and creates the new ones in a single atomic mutate.\n\nThe response is read back from Google and carries the new criterion ids.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Numeric Google platform campaign id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["schedule"],"properties":{"schedule":{"type":"array","maxItems":42,"description":"The complete set of windows. Required, so clearing the schedule is always deliberate rather than an omission.","items":{"type":"object","required":["dayOfWeek","startHour","endHour"],"properties":{"dayOfWeek":{"type":"string","enum":["MONDAY","TUESDAY","WEDNESDAY","THURSDAY","FRIDAY","SATURDAY","SUNDAY"]},"startHour":{"type":"integer","minimum":0,"maximum":23},"startMinute":{"type":"integer","enum":[0,15,30,45],"default":0,"description":"Quarter-hours only."},"endHour":{"type":"integer","minimum":0,"maximum":24,"description":"24 means midnight at the end of the day."},"endMinute":{"type":"integer","enum":[0,15,30,45],"default":0,"description":"Quarter-hours only. Must be 0 when endHour is 24."},"bidModifier":{"type":["number","null"],"minimum":0.1,"maximum":10,"description":"Bid adjustment for this window. Null runs it at the campaign bid."}}}}}},"examples":{"officeHours":{"summary":"Weekday office hours, bidding up over lunch","value":{"schedule":[{"dayOfWeek":"MONDAY","startHour":9,"endHour":17},{"dayOfWeek":"TUESDAY","startHour":9,"endHour":17},{"dayOfWeek":"WEDNESDAY","startHour":9,"endHour":12,"bidModifier":1.5},{"dayOfWeek":"WEDNESDAY","startHour":12,"endHour":17}]}},"clearSchedule":{"summary":"Serve around the clock again","value":{"schedule":[]}}}}}},"responses":{"200":{"description":"The schedule as Google stored it","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"schedule":{"type":"array","items":{"$ref":"#/components/schemas/AdScheduleWindow"}},"servesAroundTheClock":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Ads access required. Legacy plans need the Ads add-on; it is included by default on usage-based plans.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection), or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"422":{"x-summary":"The schedule breaks a Google rule, such as an overlap or an out-of-range bid modifier: fix the schedule.","description":"The schedule breaks a Google rule: too many windows on a day, an overlap, a window that ends before it starts, minutes on hour 24, or a bid modifier outside 0.1-10.0."},"501":{"description":"Not a Google Ads campaign: ad schedules are a Google criterion."}}}},"/v1/ads/campaigns/{campaignId}/bidding":{"get":{"x-resource-group":"ads","operationId":"getCampaignBidding","tags":["Ad Campaigns"],"x-platforms":["google"],"summary":"Read a campaign's current bidding","description":"Shows a Google campaign's current bidding strategy and targets, ready to prefill an edit.\n\nReads the campaign's bidding strategy on Google, cached for the quota window, for pre-filling the bid strategy block before a PUT to /v1/ads/campaigns/{campaignId}.\n\nGoogle Ads only. `platform` is required and rejected when it is anything else, since a `campaignId` is not globally unique.\n\nThe response carries `cachedAt` and `stale`, set when a quota-exhausted call falls back to the last-good copy instead of a live read.\n\n### Strategy mapping\n\nMaps Google's bidding strategy onto the same triplet PUT accepts:\n\n- `LOWEST_COST_WITHOUT_CAP`: Maximize Conversions, no target\n- `COST_CAP` + `bidAmount`: Target CPA\n- `LOWEST_COST_WITH_MIN_ROAS` + `roasAverageFloor`: Target ROAS\n- `LOWEST_COST_WITH_BID_CAP` + `bidAmount`: Maximize Clicks with a CPC ceiling\n\nA campaign on a portfolio strategy returns `portfolio` (id + name) and `bidSpec.portfolioBidStrategyId` instead of the triplet.\n\nAnything else (Manual CPC, Target Impression Share, ...) returns `bidSpec: null`; show `biddingStrategyType` as-is.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Numeric Google platform campaign id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio Google Ads SocialAccount id: resolves the customer id + refresh token."},{"name":"platform","in":"query","required":true,"schema":{"type":"string","enum":["google"]},"description":"Required: campaign IDs are not globally unique. Only \"google\" is supported today."},{"name":"adAccountId","in":"query","required":false,"schema":{"type":"string"},"description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple Google Ads accounts; optional (and inferred) when it has only one."},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string"},"description":"Alias of adAccountId, kept for existing callers"}],"responses":{"200":{"description":"Campaign bidding","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"campaignId":{"type":"string"}}},{"$ref":"#/components/schemas/CampaignBidding"}]}}}},"400":{"description":"Invalid input (accountId, adAccountId, or a non-numeric campaignId), or a platform other than \"google\""},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix it, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Not a Google Ads account: the connection behind accountId resolves to another platform."}}}},"/v1/ads/campaigns/{campaignId}":{"get":{"x-resource-group":"ads","operationId":"getAdCampaignDetails","tags":["Ad Campaigns"],"x-platforms":["meta"],"summary":"Get live campaign details","description":"Shows a Meta campaign's current settings straight from Meta, such as its objective, budget, bid strategy, schedule and delivery issues.\n\nIt reads one campaign live from Meta, returned verbatim, so a caller that knows a campaign id no longer has to page `GET /v1/ads/campaigns` to find it.\n\nThe default projection covers name, status, objective, buying type, bid strategy, budgets, spend cap, schedule and `issues_info`.\n\n### Fields and errors\n\n- `fields` is a raw-passthrough override; unknown fields return Meta's 400 verbatim.\n- A campaign the resolved connection cannot see comes back as Meta's own 400, not a 404.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Meta campaign id (platformCampaignId)."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."},{"name":"fields","in":"query","schema":{"type":"string","example":"id,name,status,daily_budget"},"description":"Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers."}],"responses":{"200":{"description":"The campaign as returned by Meta","content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"type":"object","description":"Raw Meta campaign; keys are the requested Graph fields."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}},"put":{"x-resource-group":"ads","operationId":"updateAdCampaign","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","openai","reddit","microsoft"],"summary":"Update a campaign","description":"Changes a campaign's settings, such as its name, budget, bidding or tracking URLs.\n\nSend at least one of `budget`, `bidStrategy`, `portfolioBidStrategyId`, `targetImpressionShare`, `manualCpc`, `networkSettings`, `trackingUrlTemplate`, `finalUrlSuffix`, `sharedBudgetId`, `name` or `platformSpecificData`. An unsupported field is always an error, never a silent drop.\n\n| Body field | Meta | Google | Others |\n|---|---|---|---|\n| `bidStrategy` | Yes | Yes | 501 |\n| `bidAmount`, `roasAverageFloor` | 400 (ad-set level) | Yes | 400 |\n| `portfolioBidStrategyId` | 400 | Yes | 400 |\n| `targetImpressionShare` | 400 | Search only | 400 |\n| `manualCpc` | 400 | Search and Display | 400 |\n| `networkSettings` | 400 | Search only | 400 |\n| `trackingUrlTemplate`, `finalUrlSuffix` | 400 | Yes | 400 |\n| `sharedBudgetId` | 400 | Yes | 400 |\n| `budget` (CBO; ABO returns 409) | Yes | Daily only | OpenAI and Reddit: daily or lifetime; others 501 |\n| `name` | Yes | 501 | Reddit: Yes; others 501 |\n| `platformSpecificData.spendCap` | Yes | 400 | 400 |\n| `accountId` (empty campaigns) | Yes | - | - |\n\n### Meta\n\nMeta budget edits check the live campaign budget, so an older local ABO stamp cannot block a CBO campaign. A successful edit repairs local ad budget fields. A live ABO campaign still returns 409 with the ad-set budget endpoint.\n\n`accountId` forwards the update straight to Meta for a campaign with zero ads, which would otherwise 404. The response then carries `updated: 0`.\n\n### Google bidding\n\n- `LOWEST_COST_WITHOUT_CAP` = Maximize Conversions\n- `COST_CAP` + `bidAmount` = Target CPA\n- `LOWEST_COST_WITH_MIN_ROAS` + `roasAverageFloor` = Target ROAS\n- `LOWEST_COST_WITH_BID_CAP` + `bidAmount` = Maximize Clicks with a CPC ceiling\n- `portfolioBidStrategyId` attaches a portfolio strategy instead (exclusive with `bidStrategy`)\n- `targetImpressionShare` switches the campaign to Target impression share\n- `manualCpc: { maxCpc }` switches to Manual CPC: every ad group of the campaign gets `maxCpc` as its bid, in the same mutate\n\n`targetImpressionShare` and `manualCpc` are each exclusive with every other strategy field.\n\nSetting the standard triplet on a campaign that is currently on a PORTFOLIO strategy is rejected. Detach it in Google Ads first, since it is shared across campaigns.\n\n### Google network and tracking URLs\n\n`networkSettings`, `trackingUrlTemplate` and `finalUrlSuffix` go out in one campaign update. Each field is sent written on its own leaf, so an omitted one keeps its current value. An empty string clears a URL field.\n\n### Google budgets\n\nGoogle budget updates read the current budget before mutation. Shared budgets return 409 unless allowSharedBudgetUpdate=true is explicitly supplied, because the change affects every campaign using that budget.\n\nA budget counts as shared when Google flags it as shared or when more than one campaign uses it (older budgets can serve several campaigns without the flag). Unknown sharing state also returns 409.\n\n### Google shared budgets (`sharedBudgetId`)\n\n- `sharedBudgetId` moves the campaign onto a shared budget from GET /v1/ads/shared-budgets. It also needs `allowSharedBudgetUpdate: true` (409 otherwise), because the campaign then splits that budget with every campaign on it. `budget` cannot ride along.\n- `sharedBudgetId: null` moves it back onto a new budget of its own, sized by `budget` (required, daily). The new budget and the switch go out in one atomic Google mutate.\n- A campaign that already has its own budget returns 409 for null.\n\nThe budget a campaign leaves is not removed. The response carries the budget the campaign now uses.\n\n### OpenAI Ads\n\nCampaigns carry exactly one spend cap. `budget.type` daily or lifetime replaces whichever cap the campaign had, with a minimum of 1 in the ad account's currency (422 below it).\n\nLifetime can switch to daily, but OpenAI never switches a daily cap back to lifetime (422).\n\n### Reddit Ads\n\n- `budget` changes the amount of a campaign budget (Reddit campaign budget optimization).\n- A campaign whose ad groups carry the budget returns 409 or 422; use PUT /v1/ads/ad-sets/{adSetId} there.\n- Reddit cannot switch a published budget between daily and lifetime, so `budget.type` must match the current one (422 otherwise).\n- `bidStrategy` is set per ad group on Reddit (PUT /v1/ads/ad-sets/{adSetId}).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform campaign ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform"],"properties":{"platform":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit","microsoft"],"description":"Required: platform campaign IDs are not globally unique."},"accountId":{"type":"string","description":"**Meta only.** Zernio SocialAccount id owning the ad account. Needed only for an EMPTY campaign (zero ads); ignored otherwise."},"bidStrategy":{"allOf":[{"$ref":"#/components/schemas/BidStrategy"}],"description":"**Meta + Google.**\n\n- Meta: the campaign default that ad sets inherit unless they override it.\n- Google: the campaign's own bidding strategy. LOWEST_COST_WITHOUT_CAP = Maximize Conversions, COST_CAP + bidAmount = Target CPA, LOWEST_COST_WITH_MIN_ROAS + roasAverageFloor = Target ROAS, LOWEST_COST_WITH_BID_CAP + bidAmount = Maximize Clicks with a CPC ceiling.\n- Google: portfolioBidStrategyId attaches a portfolio strategy instead.\n"},"bidAmount":{"type":"number","description":"**Google only.** Whole currency units (USD: 12 = $12.00). Max CPC for LOWEST_COST_WITH_BID_CAP, CPA target for COST_CAP; required for both."},"roasAverageFloor":{"type":"number","description":"**Google only.** Decimal ROAS multiplier (2.0 = 2.0x), required for LOWEST_COST_WITH_MIN_ROAS."},"portfolioBidStrategyId":{"type":"string","pattern":"^\\d+$","description":"**Google only.** Attach an existing portfolio bid strategy (numeric id from GET /v1/ads/bid-strategies) instead of setting bidStrategy. Exclusive with bidStrategy."},"allowSharedBudgetUpdate":{"type":"boolean","default":false,"description":"Google only. Explicitly allow changing a shared campaign budget (flagged as shared by Google, or used by more than one campaign), affecting every campaign that uses it. Does not bypass an unknown sharing state. Also required to move a campaign onto a shared budget with sharedBudgetId."},"targetImpressionShare":{"allOf":[{"$ref":"#/components/schemas/GoogleTargetImpressionShare"}],"description":"Google Search only. Target impression share bidding. Exclusive with bidStrategy, portfolioBidStrategyId and manualCpc; bidAmount is refused alongside it (the ceiling is maxCpc)."},"manualCpc":{"$ref":"#/components/schemas/GoogleManualCpc"},"networkSettings":{"$ref":"#/components/schemas/GoogleNetworkSettings"},"trackingUrlTemplate":{"type":"string","description":"**Google only.** campaign.tracking_url_template; an empty string clears it."},"finalUrlSuffix":{"type":"string","description":"**Google only.** campaign.final_url_suffix; an empty string clears it."},"sharedBudgetId":{"type":["string","null"],"pattern":"^\\d+$","description":"**Google only.** Move the campaign onto this shared budget (id from GET /v1/ads/shared-budgets), or null to move it back onto a budget of its own sized by `budget`."},"budget":{"type":"object","description":"Meta CBO, Google daily, or OpenAI Ads or Reddit Ads daily or lifetime campaign budget, in whole currency units.","required":["amount","type"],"properties":{"amount":{"type":"number","description":"Budget amount in the ad account's currency"},"type":{"type":"string","enum":["daily","lifetime"]}}},"name":{"type":"string","maxLength":255,"description":"**Meta and Reddit.** Rename the campaign."},"platformSpecificData":{"type":"object","description":"**Meta only.** Platform implied by the `platform` body param, same convention as POST /v1/ads/create.","properties":{"spendCap":{"type":["number","null"],"description":"Campaign lifetime spend cap, in the ad account's currency (Meta `spend_cap`). Pass null to remove the cap; 0 is rejected by Meta."}}}}},"example":{"platform":"facebook","budget":{"amount":8,"type":"daily"}}}}},"responses":{"200":{"description":"Campaign updated","content":{"application/json":{"schema":{"type":"object","description":"Echoes back only the fields you sent, plus `updated`.","properties":{"updated":{"type":"integer","description":"Local Ad documents mirrored. 0 on the empty-campaign path."},"budget":{"$ref":"#/components/schemas/AdCampaignBudget"},"budgetLevel":{"type":"string","enum":["campaign"]},"bidStrategy":{"$ref":"#/components/schemas/BidStrategy"},"bidAmount":{"type":"number"},"roasAverageFloor":{"type":"number"},"portfolioBidStrategyId":{"type":"string","description":"Google only. Echoed back, but NOT mirrored onto local Ad documents (no column for it yet)."},"targetImpressionShare":{"$ref":"#/components/schemas/GoogleTargetImpressionShare"},"manualCpc":{"$ref":"#/components/schemas/GoogleManualCpc"},"networkSettings":{"$ref":"#/components/schemas/GoogleNetworkSettings"},"trackingUrlTemplate":{"type":"string"},"finalUrlSuffix":{"type":"string"},"sharedBudgetId":{"type":["string","null"],"description":"Google only. Echoed back when the campaign moved budgets; `budget` is then the budget it now uses."},"platformSpecificData":{"type":"object"}}}}}},"400":{"description":"Invalid input, or a field the resolved platform does not support at the campaign level (see the support table)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The free live ads limit is reached without a card, or the account is not selected: add a card or select it.","description":"Returned with these codes:\n\n- `ads_allowance_exceeded`: the team has no payment method on file and has reached the 500 free live ads. Add a card to resume.\n- `ad_account_not_selected`: the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n- `ad_account_not_selected` fix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection), or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"x-summary":"The campaign budget setup blocks this update, or the connection is inactive: fix the request, or reconnect and reread the account ID.","description":"Meta campaign is ABO, or the Google budget is shared without allowSharedBudgetUpdate=true, or sharing state cannot be verified. The account may also be inactive or need reconnection (code ads_connection_required). Reconnect it and read GET /v1/accounts for its current ID before retrying."},"501":{"description":"Operation not supported on this platform"}}},"delete":{"x-resource-group":"ads","operationId":"deleteAdCampaign","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","openai","reddit","microsoft"],"summary":"Delete a campaign","description":"Deletes a campaign on its platform, including a campaign that never got any ads.\n\nOnly the campaign itself is sent to the platform:\n\n- Meta, Google, TikTok, LinkedIn and X delete it.\n- OpenAI, Reddit and Pinterest have no campaign delete and archive it instead (see below).\n\nLocally, all Ad documents for this campaign are marked `status: cancelled`.\n\n### Empty campaigns\n\nA campaign with zero ads has no local Ad documents to resolve, so it is invisible to `/v1/ads/tree` and this endpoint would 404. That state comes from the two-step create flow (campaign, then ads via `existingCampaignId`) whenever Meta rejects the ad step.\n\nTo delete such a shell, send `accountId` in the body or the query string. We skip the local lookup entirely and forward the delete to the platform of that connection. `accountId` is ignored when the campaign does have ads.\n\n### Google, TikTok, LinkedIn, Pinterest, Reddit and OpenAI\n\nGoogle, TikTok, LinkedIn, Pinterest and Reddit take the ad account from the synced campaign (OpenAI needs none). When the campaign was never synced (or is synced under several ad accounts), the answer is 409 `invalid_resource_state` on `campaignId` and nothing is deleted: sync the ad account and retry.\n\nBefore deleting on Google, TikTok, LinkedIn, Pinterest, OpenAI or Reddit, Zernio asks the platform whether the campaign still holds ad groups or ads. Google asset groups count; on LinkedIn, campaigns inside the campaign group count.\n\nIf it does, or the platform cannot confirm it has none (a TikTok Smart+ campaign), the answer is 409 `invalid_resource_state` on `campaignId` and nothing is deleted. Either:\n\n- sync the ad account and delete the campaign again so its ads are cancelled with it, or\n- delete them on the platform first.\n\n### X\n\nOn X the ad account comes from the synced campaign, which wins over `adAccountId`. When the campaign was never synced, send `adAccountId` too.\n\nBefore deleting, Zernio asks X whether the campaign still holds undeleted line items (ads not synced yet). If it does, the answer is 409 `invalid_field_value` on `campaignId` and nothing is deleted.\n\n- Line items that hold promoted posts: sync the ad account and retry.\n- Line items without promoted posts never sync, so delete them in X Ads Manager first.\n\n### Reddit Ads\n\nReddit Ads has no delete: the campaign is archived instead (`configured_status` ARCHIVED), which stops delivery for good. Its ad groups and ads keep their own switches but cannot deliver under an archived campaign.\n\n### OpenAI Ads\n\nOpenAI Ads has no delete either: the campaign is archived (state `archive`). Its ad groups and ads are not touched on OpenAI.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform campaign ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform"],"properties":{"platform":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit","microsoft"]},"accountId":{"type":"string","description":"Zernio SocialAccount id owning the ad account. Required only to delete an EMPTY campaign (zero ads), which has no local Ad documents to resolve a token from."},"adAccountId":{"type":"string","pattern":"^[0-9a-z]{1,32}$","description":"X only, for an EMPTY campaign that was never synced: the X ad account id the campaign belongs to (lowercase letters and digits). The synced campaign's ad account wins when there is one. Also accepted on the query string."}}}}}},"responses":{"200":{"description":"Campaign deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"adCount":{"type":"integer","description":"Number of local Ad docs marked cancelled"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"x-summary":"The campaign cannot be deleted yet and nothing was removed: reconnect the connection or sync the ad account, then retry.","description":"One of three conflicts:\n\n- The ads connection is inactive or needs reconnection (code `ads_connection_required`, param `accountId`). Reconnect it, then read GET /v1/accounts for its current account ID before retrying.\n- X only: the empty campaign still holds line items on X (code `invalid_field_value`, param `campaignId`) and nothing was deleted. Sync the ad account when they hold promoted posts, otherwise delete them in X Ads Manager, then retry.\n- Google, TikTok, LinkedIn, Pinterest, OpenAI or Reddit: the empty campaign has no synced record naming its ad account, or the platform still lists ad groups or ads under it (code `invalid_resource_state`, param `campaignId`). Nothing was deleted: sync the ad account, then retry.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"connectionRequired":{"summary":"Ads connection needs reconnection","value":{"error":"This account needs reconnection. Reconnect the account, then read GET /v1/accounts for its current account ID before retrying.","type":"invalid_request_error","code":"ads_connection_required","param":"accountId"}},"xCampaignHoldsLineItems":{"summary":"X campaign still holds line items","value":{"error":"This X campaign still holds line items on X that Zernio has not synced, so it is not empty and was not deleted. If they hold promoted posts, sync the ad account (POST /v1/ads/sync), then delete the campaign again so its ads are cancelled with it. Line items without promoted posts never sync into Zernio: delete them in X Ads Manager, then delete the campaign again.","type":"invalid_request_error","code":"invalid_field_value","param":"campaignId","platform":"twitter"}},"emptyCampaignNotSynced":{"summary":"Empty campaign with no synced ad account","value":{"error":"This Google Ads campaign has no ads and no synced record naming its ad account, so it was not deleted. Sync the ad account (POST /v1/ads/sync), then delete the campaign again.","type":"invalid_request_error","code":"invalid_resource_state","param":"campaignId","platform":"google"}},"emptyCampaignHoldsChildren":{"summary":"Platform still lists ad groups or ads under the campaign","value":{"error":"This OpenAI Ads campaign has no ads on Zernio but OpenAI Ads still lists ad groups or ads under it (or Zernio cannot confirm it has none), so it was not deleted. Sync the ad account (POST /v1/ads/sync) and delete the campaign again so its ads are cancelled with it, or delete its ad groups and ads in OpenAI Ads first.","type":"invalid_request_error","code":"invalid_resource_state","param":"campaignId","platform":"openai"}}}}}},"501":{"description":"Operation not supported on this platform"}}}},"/v1/ads/campaigns/{campaignId}/negative-keywords":{"get":{"x-resource-group":"ads","operationId":"listCampaignNegativeKeywords","tags":["Ad Campaigns"],"x-platforms":["google"],"summary":"List campaign-level negative keywords","description":"Lists the negative keywords set on a whole Google campaign, separate from ad group negatives.\n\nIt returns the campaign-level negative keywords (`campaign_criterion.negative`), distinct from the ad-group-level negatives under `GET /v1/ads/keywords`.\n\n### Caching and quota\n\nResults are cached for the quota window (not synced to Postgres) and gated by the shared Google Ads operations budget, like every other on-demand Google surface.\n\nThe response carries `cachedAt` and `stale`, set when a quota-exhausted call falls back to the last-good copy instead of a live read.\n\n### Platform\n\nThe platform is always discovered from the campaign itself. A non-Google campaign returns 501 rather than 404, whether or not `platform` was passed.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform campaign ID"},{"name":"platform","in":"query","schema":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit"]},"description":"Optional and NOT authoritative: the resolved campaign's own platform decides 200 vs 501, never this hint."}],"responses":{"200":{"description":"Campaign-level negative keywords","content":{"application/json":{"schema":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"object","properties":{"criterionId":{"type":"string"},"text":{"type":"string"},"matchType":{"type":"string","enum":["exact","phrase","broad"]}}}},"cachedAt":{"type":["string","null"],"format":"date-time","description":"When this list was fetched from Google. Null when it was never served from cache."},"stale":{"type":"boolean","description":"True when Google's daily API quota was exhausted and this is the last successful fetch, not a live read."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"description":"Campaign not found"},"429":{"description":"Google Ads operations budget exhausted; retry later"},"501":{"description":"Only available on Google Ads campaigns"}}},"put":{"x-resource-group":"ads","operationId":"replaceCampaignNegativeKeywords","tags":["Ad Campaigns"],"x-platforms":["google"],"summary":"Replace campaign-level negative keywords","description":"Replaces a Google campaign's full list of campaign-level negative keywords, or clears it.\n\nReplaces the FULL set of campaign-level negative keywords (C.270): the desired\nlist is diffed against what Google already has, and the difference is applied\nas one `create`/`remove` mutate. Send an empty array to clear every campaign\nnegative.\n\nThe platform is always discovered from the campaign itself; a non-Google\ncampaign returns 501 rather than 404, whether or not `platform` was sent.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform campaign ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["keywords"],"properties":{"platform":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit"],"description":"Optional and NOT authoritative: the resolved campaign's own platform decides 200 vs 501, never this hint."},"keywords":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/KeywordEntry"}}}}}}},"responses":{"200":{"description":"Campaign-level negative keywords replaced","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"integer","description":"Negative criteria newly created on Google"},"removed":{"type":"integer","description":"Negative criteria removed from Google"},"keywords":{"type":"array","description":"The full negative-keyword set after the replace","items":{"type":"object","properties":{"criterionId":{"type":"string"},"text":{"type":"string"},"matchType":{"type":"string","enum":["exact","phrase","broad"]}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"description":"Campaign not found"},"429":{"description":"Google Ads operations budget exhausted; retry later"},"501":{"description":"Only available on Google Ads campaigns"}}}},"/v1/ads/campaigns/bulk-status":{"post":{"x-resource-group":"ads","operationId":"bulkUpdateAdCampaignStatus","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit","microsoft"],"summary":"Pause or resume many campaigns","description":"Pauses or resumes up to 50 campaigns in one call, with a separate result per campaign so one failure does not block the rest.\n\nEach campaign is updated concurrently, and the response contains a per-campaign result so a single bad row does not fail the whole batch.\n\nEach campaign is read, written and re-read exactly as PUT /v1/ads/campaigns/{campaignId}/status describes: only the campaign's own switch is written, never its ad sets' or ads'.\n\n`updated` / `skipped` count campaigns.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status","campaigns"],"properties":{"status":{"type":"string","enum":["active","paused"]},"campaigns":{"type":"array","maxItems":50,"items":{"type":"object","required":["platformCampaignId","platform"],"properties":{"platformCampaignId":{"type":"string","description":"The campaign id on the ad platform (e.g. the numeric Google campaign id), not a Zernio id."},"platform":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit","microsoft","googleads","tiktokads","linkedinads","pinterestads","xads","openaiads","redditads","microsoftads"],"description":"The ad platform, e.g. `google` for Google Ads. The ads connection slug (`googleads`, `tiktokads`, ...) is accepted as an alias. `metaads` is not: send `facebook` or `instagram`."}}}}}},"example":{"status":"paused","campaigns":[{"platformCampaignId":"23456789012","platform":"google"},{"platformCampaignId":"120210000000000000","platform":"facebook"}]}}}},"responses":{"200":{"description":"Per-campaign results","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","paused"]},"totals":{"type":"object","properties":{"updated":{"type":"integer"},"skipped":{"type":"integer"},"failed":{"type":"integer"}}},"results":{"type":"array","items":{"type":"object","properties":{"platformCampaignId":{"type":"string"},"platform":{"type":"string"},"updated":{"type":"integer","enum":[0,1]},"skipped":{"type":"integer","enum":[0,1]},"platformCampaignStatus":{"type":["string","null"],"description":"The campaign's own switch read back from the platform; null when it could not be read."},"error":{"type":"string"}}}}}}}}},"400":{"description":"Invalid input"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The free live ads limit is reached without a card: add a card to resume.","description":"Returned with code `ads_allowance_exceeded` when the team has no payment method on file and has reached the 500 free live ads: add a card to resume."}}}},"/v1/ads/campaigns/{campaignId}/duplicate":{"post":{"x-resource-group":"ads","operationId":"duplicateAdCampaign","tags":["Ad Campaigns"],"x-platforms":["meta","tiktok","linkedin"],"summary":"Duplicate a campaign","description":"Copies a campaign with its ad sets, ads, creatives and targeting, created paused so you can review it before launch.\n\nAd sets, ads, creatives, and targeting are copied by default (`deepCopy: true`). The copy is created paused so callers can review before launching.\n\n### Per-platform implementation\n\n- **Meta** copies one level at a time with Meta's `/copies` endpoint. See below.\n- **TikTok** has no native copy primitive. See below.\n- **LinkedIn** has no native copy primitive. See below.\n- Other platforms return 501 Not Implemented.\n\n### Meta\n\nZernio copies the campaign, then each of its ad sets (DELETED and ARCHIVED ones are skipped), then each ad of every ad set. So a campaign of any size copies: Meta refuses a single deep copy of 3 or more objects.\n\n- `statusOption` applies at every level.\n- If any child copy fails, the partial copy is deleted and the request fails with Meta's error, so a retry starts clean.\n- Each copied object takes a few seconds, so a large campaign takes minutes to answer.\n\n### TikTok\n\nZernio walks the source graph (`/v2/campaign/get/`, `/v2/adgroup/get/`, `/v2/ad/get/`) and recreates each entity via the corresponding `/create/` endpoints. It carries over budget / targeting / bid_type / bid_price / deep_bid_type / creative fields. Spark Ad linkage (`tiktok_item_id`) is preserved.\n\n### LinkedIn\n\nZernio walks the source CampaignGroup → Campaigns → Creatives and recreates each entity. It carries over these fields, plus every Creative's `content` object verbatim:\n\n- `type` / `costType` / `unitCost` / `optimizationTargetType`\n- `creativeSelection` / `objectiveType` / `format`\n- `dailyBudget` / `totalBudget` / `targetingCriteria` / `runSchedule`\n\n`statusOption: INHERITED_FROM_SOURCE` is evaluated **per entity**: any Group / Campaign / Creative whose source is `ACTIVE` gets its clone activated too.\n\nDuplicating an ACTIVE campaign with `INHERITED_FROM_SOURCE` starts a second front of spend the moment the clone activates. The safe default is `PAUSED`.\n\n### Sync\n\nThe copy exists on the platform when this call returns. The new hierarchy reaches our DB through a sync discovery that starts automatically and runs after the response, usually within a few minutes.\n\nPoll `/v1/ads/tree` until it appears; until then, calls that take a copied id return 404, so retry them. Set `syncAfter: false` to skip the sync; the copy then appears on a later scheduled sync.\n","security":[{"bearerAuth":[]}],"parameters":[{"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.\n\n- Same key + same body: replays the original response.\n- Same key + different body: 422.\n- Key still processing: 409.\n\nOnly 2xx responses are stored, so a request that failed with a 4xx can be retried with a corrected body under the SAME key.\n"},{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Source platform campaign ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform"],"properties":{"platform":{"type":"string","enum":["facebook","instagram","tiktok","linkedin"]},"deepCopy":{"type":"boolean","default":true,"description":"Copy child ad sets + ads + creatives + targeting"},"statusOption":{"type":"string","enum":["ACTIVE","PAUSED","INHERITED_FROM_SOURCE"],"default":"PAUSED","description":"ACTIVE = launch the clone immediately (spends the moment LinkedIn approves it). PAUSED = clone stays DRAFT, safe default. INHERITED_FROM_SOURCE = mirror each entity's source status per-entity. Duplicating an ACTIVE campaign this way starts a second front of spend.\n"},"startTime":{"type":"string","format":"date-time","description":"Reschedule the copied hierarchy's start (ISO 8601). TikTok defaults to a start a few minutes after the copy.\n\n- Meta and TikTok: a value without an offset (`YYYY-MM-DD`, `YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DDTHH:MM:SS`) is read in the ad account timezone.\n- LinkedIn: ad accounts carry no timezone, so it is read as UTC."},"endTime":{"type":"string","format":"date-time","description":"Reschedule the copied hierarchy's end, read like `startTime`; a date-only end runs to 23:59:59 local. Defaults to the source's end."},"renameStrategy":{"type":"string","enum":["DEEP_RENAME","ONLY_TOP_LEVEL_RENAME","NO_RENAME"],"description":"Meta's native `rename_strategy` values:\n\n- `DEEP_RENAME`: renames the copied campaign and every copied child (ad sets, ads) with `renamePrefix` / `renameSuffix`.\n- `ONLY_TOP_LEVEL_RENAME`: renames only the copied campaign; children keep their source names.\n- `NO_RENAME`: keeps every source name.\n\nWith no rename option at all, Meta appends its own ` - Copy` suffix; LinkedIn defaults to `DEEP_RENAME` (its campaign group and campaigns are renamed). Ignored on TikTok, where `renamePrefix` / `renameSuffix` apply to every copied object.\n"},"renamePrefix":{"type":"string","description":"Text prepended to each renamed object's name."},"renameSuffix":{"type":"string","description":"Text appended to each renamed object's name. On LinkedIn an omitted suffix defaults to ` (Copy)`."},"syncAfter":{"type":"boolean","default":true,"description":"Trigger ads discovery on the owning account after the copy succeeds"}}}}}},"responses":{"200":{"description":"Campaign duplicated","content":{"application/json":{"schema":{"type":"object","properties":{"copiedCampaignId":{"type":"string","description":"Platform ID of the new campaign"},"adSetIdMap":{"type":"object","additionalProperties":{"type":"string"},"description":"Meta only: source ad set ID to copied ad set ID. Empty when `deepCopy` is false."},"adIdMap":{"type":"object","additionalProperties":{"type":"string"},"description":"Meta only: source ad ID to copied ad ID, across every copied ad set. Empty when `deepCopy` is false."},"discovery":{"type":"string","enum":["triggered","skipped","failed"],"description":"The copy exists on the platform in all three cases.\n\n- `triggered`: an ads sync started and runs after this response, so the copy may not be readable through Zernio yet.\n- `skipped`: no sync started, so the copy appears on a later scheduled sync.\n- `failed`: the sync could not start. A sync that errors after the response is not reported here."},"raw":{"type":"object","description":"Platform-native response from the copy (TikTok and LinkedIn). Absent on Meta, which returns `adSetIdMap` and `adIdMap` instead."}}}}}},"400":{"description":"Invalid input"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The free live ads limit is reached without a card, or the account is not selected: add a card or select it.","description":"One of two refusals:\n\n- `ads_allowance_exceeded`: the team has no payment method on file and has reached the 500 free live ads. Add a card to resume.\n- `ad_account_not_selected`: the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"description":"Source campaign not found"},"429":{"$ref":"#/components/responses/MetaAdAccountWriteLimited"},"501":{"description":"Operation not supported on this platform"}}}},"/v1/ads/campaigns/{campaignId}/targeting":{"get":{"x-resource-group":"ads","operationId":"getCampaignTargeting","tags":["Ad Campaigns"],"x-platforms":["google"],"summary":"Read a Google campaign's device, location, excluded location, and language targeting","description":"Shows a Google campaign's device, location, excluded location and language targeting so you can build an editor for it.\n\nGoogle Ads compliance requires geo, language, budget, and bidding targeting set at creation to stay editable afterwards. This reads the campaign state so an integrator can build an editor around it.\n\n- Cached for the quota window (10 minutes fresh, up to 7 days last-good), not always a live read.\n- Google only; every other platform returns 501.\n\n### Devices\n\n`devices` lists the device criteria the campaign carries, which depends on its channel:\n\n- Search campaigns have MOBILE, DESKTOP and TABLET.\n- Display campaigns also have CONNECTED_TV.\n\n`bidModifier` is Google's bid adjustment for that device: `null` when it has none, and `0` when the device is switched off. `included` is false for exactly that case.\n\n### Locations\n\n`excludedLocations` lists the campaign's negative location criteria (the places it never serves in).\n\n`locations` still lists every location criterion, each flagged with `negative`, so a client reading the targeted set filters `negative: false`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Google platform campaign ID"},{"name":"platform","in":"query","schema":{"type":"string","enum":["google"]},"description":"Disambiguates when the same campaignId string exists on more than one connected platform."}],"responses":{"200":{"description":"Current campaign targeting","content":{"application/json":{"schema":{"type":"object","properties":{"devices":{"type":"array","items":{"type":"object","properties":{"device":{"type":"string","enum":["MOBILE","DESKTOP","TABLET","CONNECTED_TV"]},"included":{"type":"boolean"},"bidModifier":{"type":["number","null"],"description":"Google's bid adjustment for this device: null when it has none, 0 when the device is switched off, otherwise 0.1 to 10."}}}},"locations":{"type":"array","items":{"type":"object","properties":{"geoTargetId":{"type":"string","description":"Numeric id from Google's geoTargetConstants/{id}."},"negative":{"type":"boolean","description":"true = excluded location."},"name":{"type":["string","null"],"description":"Google's geo_target_constant.name, e.g. \"United States\"; null when the id could not be resolved."},"canonicalName":{"type":["string","null"],"description":"Google's geo_target_constant.canonical_name, e.g. \"California, United States\"; null when the id could not be resolved."},"type":{"type":["string","null"],"description":"Google's geo_target_constant.target_type, e.g. \"Country\", \"Region\", \"City\"; null when the id could not be resolved."},"countryCode":{"type":["string","null"],"description":"Google's geo_target_constant.country_code, an ISO 3166-1 alpha-2 code; null when the id could not be resolved."}}}},"excludedLocations":{"type":"array","description":"The negative (excluded) location criteria, same item shape as `locations` with `negative: true`.","items":{"type":"object","properties":{"geoTargetId":{"type":"string","description":"Numeric id from Google's geoTargetConstants/{id}."},"negative":{"type":"boolean","description":"Always true here."},"name":{"type":["string","null"]},"canonicalName":{"type":["string","null"]},"type":{"type":["string","null"]},"countryCode":{"type":["string","null"]}}}},"excludedLocationsEditable":{"type":"boolean","description":"Whether PUT accepts `excludedLocations` for this campaign. False on Demand Gen, which returns 400 for any exclusion."},"languages":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Google's language code (ISO 639-1, plus variants such as `zh_CN`). Empty when the campaign's language_constant id is not in Zernio's checked-in table."},"id":{"type":"string","description":"Google's languageConstants/{id} numeric id."},"name":{"type":"string"}}}},"locationTargetingType":{"type":["string","null"],"enum":["presence","presence_or_interest",null],"description":"Who the location targeting reaches, see GoogleLocationTargetingType. Null when Google reports a legacy value (SEARCH_INTEREST) this API does not set."},"cachedAt":{"type":["string","null"],"format":"date-time","description":"When this targeting was fetched from Google. Null when it was never served from cache."},"stale":{"type":"boolean","description":"True when Google's daily API quota was exhausted and this is the last successful fetch, not a live read."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads access required (Ads add-on on legacy plans, included on usage-based plans)."},"404":{"description":"Campaign not found"},"501":{"description":"Only available on Google Ads campaigns"}}},"put":{"x-resource-group":"ads","operationId":"updateCampaignTargeting","tags":["Ad Campaigns"],"x-platforms":["google"],"summary":"Edit a Google campaign's device, location, excluded location, or language targeting","description":"Changes a Google campaign's device, location, excluded location or language targeting after it was created. Google only; every other platform returns 501.\n\nGoogle Ads compliance row M.10: geo and language targeting set at creation must stay editable afterwards.\n\nSend at least one of `devices`, `locations`, `excludedLocations`, `languages`, `locationTargetingType`. Each provided field REPLACES that field's existing criteria on the campaign (a full set, not a delta). Fields left out of the body are untouched.\n\n### Fields\n\n- `devices`: the full set of device bid modifiers. A supported device you leave out is switched off with a bid modifier of 0, since Google cannot remove a device criterion. A device the campaign's channel does not carry, and a set that switches every device off, both return 422.\n- `locations`: see below.\n- `excludedLocations`: see below.\n- `languages`: an array of Google's language codes (ISO 639-1, plus variants such as `zh_CN`). An unknown code returns 400.\n- `locationTargetingType`: switches who the location targeting reaches. `presence` (people in or regularly in the locations) or `presence_or_interest` (also people searching for or interested in them). Example: `{ \"platform\": \"google\", \"targeting\": { \"locationTargetingType\": \"presence\" } }`.\n\n### Locations\n\n`locations` accepts the same shapes as campaign creation: a bare array of ISO country codes, or an object with `countries`/`regions`/`cities`/`zips`/`metros` key lists (`key` from GET /v1/ads/targeting/search?dimension=geo).\n\nExcluded locations are left untouched by `locations`. An empty location list returns 400 instead of removing every criterion: a Google campaign with no location criteria targets every country, so omit `locations` to leave targeting alone.\n\n### Excluded locations\n\n`excludedLocations` takes the same two shapes and replaces the campaign's negative location criteria (the places it never serves in), leaving the targeted `locations` untouched.\n\n- An empty list (or `{}`) removes every exclusion.\n- Radius exclusions are not supported.\n- A place cannot be both targeted and excluded: a request whose result would leave one on both sides returns 400 before anything is written.\n- Moving a place from one side to the other in the same request is applied atomically.\n\nExample: `{ \"platform\": \"google\", \"targeting\": { \"excludedLocations\": { \"countries\": [\"CA\"], \"regions\": [\"21137\"] } } }`.\n\n### Atomic writes and response\n\nThe removes and the creates go out in ONE Google `googleAds:mutate`, so a failed edit leaves the campaign's previous set intact rather than a half-applied one.\n\nThe response includes the refreshed `devices`/`locations`/`excludedLocations`/`languages` state read back from Google after the edit. It also invalidates the cached copy `GET` on this campaign would otherwise keep serving.\n\n### Demand Gen\n\nGoogle keeps a Demand Gen campaign's locations and languages on its ad groups and refuses them on the campaign.\n\n- With one ad group, they are written there and the response carries its `adGroupId` (the campaign-level `locations`/`languages` read back then stay empty).\n- With several ad groups, the call returns 400 naming them. Edit each one with PUT /v1/ads/{adId} `targeting` on an ad of that ad group.\n- Campaigns migrated from Discovery that still target on the campaign keep being written there.\n- `devices` and `locationTargetingType` stay campaign-level.\n- `excludedLocations` is not available on Demand Gen yet and returns 400.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Google platform campaign ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform","targeting"],"properties":{"platform":{"type":"string","enum":["google"]},"targeting":{"type":"object","minProperties":1,"properties":{"devices":{"type":"array","items":{"oneOf":[{"type":"string","enum":["MOBILE","DESKTOP","TABLET","CONNECTED_TV"]},{"type":"object","required":["device","bidModifier"],"properties":{"device":{"type":"string","enum":["MOBILE","DESKTOP","TABLET","CONNECTED_TV"]},"bidModifier":{"type":"number","description":"Bid modifier for this device; devices without one use the campaign's base bid."}}}]},"description":"Devices to include. Devices not listed become excluded (negative) criteria, same contract as the existing devices-only edit."},"locations":{"description":"Bare country-code array, or the nested creation-time shape (countries/regions/cities/zips/metros).","oneOf":[{"type":"array","items":{"type":"string","description":"ISO 3166-1 alpha-2 country code."}},{"type":"object","properties":{"countries":{"type":"array","items":{"type":"string"}},"regions":{"type":"array","items":{"oneOf":[{"type":"string","description":"The geo target constant id alone."},{"type":"object","required":["key"],"properties":{"key":{"type":"string"},"name":{"type":"string"}}}]}},"cities":{"type":"array","items":{"oneOf":[{"type":"string","description":"The geo target constant id alone."},{"type":"object","required":["key"],"properties":{"key":{"type":"string"},"name":{"type":"string"}}}]}},"zips":{"type":"array","items":{"oneOf":[{"type":"string","description":"The geo target constant id alone."},{"type":"object","required":["key"],"properties":{"key":{"type":"string"},"name":{"type":"string"}}}]}},"metros":{"type":"array","items":{"oneOf":[{"type":"string","description":"The geo target constant id alone."},{"type":"object","required":["key"],"properties":{"key":{"type":"string"},"name":{"type":"string"}}}]}}}}]},"languages":{"type":"array","items":{"type":"string"},"description":"Google's language codes (ISO 639-1, plus variants such as `zh_CN`), e.g. [\"en\", \"de\"]."},"excludedLocations":{"description":"Locations the campaign never serves in, as a bare country-code array or the nested countries/regions/cities/zips/metros shape. Replaces the excluded set; [] removes every exclusion.","oneOf":[{"type":"array","items":{"type":"string","description":"ISO 3166-1 alpha-2 country code."}},{"type":"object","additionalProperties":false,"properties":{"countries":{"type":"array","items":{"type":"string"}},"regions":{"type":"array","items":{"oneOf":[{"type":"string","description":"The geo target constant id alone."},{"type":"object","required":["key"],"properties":{"key":{"type":"string"},"name":{"type":"string"}}}]}},"cities":{"type":"array","items":{"oneOf":[{"type":"string","description":"The geo target constant id alone."},{"type":"object","required":["key"],"properties":{"key":{"type":"string"},"name":{"type":"string"}}}]}},"zips":{"type":"array","items":{"oneOf":[{"type":"string","description":"The geo target constant id alone."},{"type":"object","required":["key"],"properties":{"key":{"type":"string"},"name":{"type":"string"}}}]}},"metros":{"type":"array","items":{"oneOf":[{"type":"string","description":"The geo target constant id alone."},{"type":"object","required":["key"],"properties":{"key":{"type":"string"},"name":{"type":"string"}}}]}}}}]},"locationTargetingType":{"$ref":"#/components/schemas/GoogleLocationTargetingType"}}}}}}}},"responses":{"200":{"description":"Targeting updated","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"adGroupId":{"type":"string","description":"Demand Gen only: the ad group that received the locations and languages."},"updated":{"type":"array","items":{"type":"string","enum":["devices","locations","excludedLocations","languages","locationTargetingType"]},"description":"Which targeting fields were applied."},"locationTargetingType":{"type":["string","null"],"enum":["presence","presence_or_interest",null],"description":"The value read back from Google after the edit."},"devices":{"type":"array","items":{"type":"object","properties":{"device":{"type":"string","enum":["MOBILE","DESKTOP","TABLET","CONNECTED_TV"]},"included":{"type":"boolean"},"bidModifier":{"type":["number","null"],"description":"Always null on this read; see GET's description."}}}},"locations":{"type":"array","items":{"type":"object","properties":{"geoTargetId":{"type":"string","description":"Numeric id from Google's geoTargetConstants/{id}."},"negative":{"type":"boolean","description":"true = excluded location."},"name":{"type":["string","null"],"description":"Google's geo_target_constant.name; see GET's description."},"canonicalName":{"type":["string","null"],"description":"Google's geo_target_constant.canonical_name; see GET's description."},"type":{"type":["string","null"],"description":"Google's geo_target_constant.target_type; see GET's description."},"countryCode":{"type":["string","null"],"description":"Google's geo_target_constant.country_code; see GET's description."}}}},"excludedLocations":{"type":"array","description":"The negative (excluded) location criteria read back after the edit, same item shape as `locations`.","items":{"type":"object","properties":{"geoTargetId":{"type":"string"},"negative":{"type":"boolean"},"name":{"type":["string","null"]},"canonicalName":{"type":["string","null"]},"type":{"type":["string","null"]},"countryCode":{"type":["string","null"]}}}},"languages":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The free live ads limit is reached without a card, or the account is not selected: add a card or select it.","description":"Returned with one of these codes:\n\n- `ads_allowance_exceeded`: the team has no payment method on file and has reached the 500 free live ads. Add a card to resume.\n- `ad_account_not_selected`: the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"description":"Campaign not found"},"501":{"description":"Only available on Google Ads campaigns"}}}},"/v1/ads/ad-sets":{"get":{"x-resource-group":"ads","operationId":"listAdSets","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","openai","reddit","microsoft"],"summary":"List ad sets","description":"Lists ad sets (ad groups on Google) with their targeting, bidding and optimization settings, optionally for one campaign.\n\nReturns the ad sets (Google ad groups) synced for the connection, optionally filtered by platform and campaignId.\n\nIt reads the `ad_sets` table directly, independent of the `ads` rollup GET /v1/ads/tree uses. So a newly created standalone ad group with no ad yet (POST /v1/ads/ad-sets, Google only) is visible here. It stays invisible in the tree until an ad joins it via `adSetId` on POST /v1/ads/create.\n\n### Paging\n\nRows come newest first (by platform creation time, then id, so pages never overlap), 500 per page unless `limit` says otherwise. `pagination.total` counts every matching ad set and `page` reaches the rest.\n\n### Synced config\n\n**This list is SYNCED, not live** (refreshed by background sync, see below). Each row also carries the ad set's config: `targeting`, `bidStrategy`, `bidAmount`, `optimizationGoal`, `billingEvent`, `promotedObject`.\n\nSo `?accountId=...&adAccountId=act_...` returns the config of every ad set of an ad account in one call, without a `campaignId`.\n\nTo read budgets, status, targeting, promoted object and bid strategy of every campaign and ad set of a Meta ad account LIVE in one call (for example as a pre-write spend gate), use GET /v1/ads/accounts/live instead.\n\n### Status freshness\n\n`status`, `configuredStatus`, `platformStatus`, `platformAdSetStatus` and `platformCampaignStatus` are the values Zernio last stored.\n\nBackground sync refreshes them, typically within 15 to 60 minutes (Google up to about 3 hours). Ended or long-paused objects may be refreshed less often. Zernio's own status writes re-read the switches they change.\n\nA change made in the platform's own ads manager therefore shows up here only after the next sync.\n\n### Live reads (`live=true`)\n\nControllers that act on a switch should pass `live=true`. It reads the switches from the platform now, stores them, and returns `statusReadAt` (null when the read failed and the stored values were returned).\n\n- `live=true` needs a `campaignId` or `adSetId` filter.\n- Each listed ad set's own switch (`platformAdSetStatus`) is read live for the first 20 rows of the page. Later rows keep their synced value with `statusReadAt: null`.\n- To read more ad sets live, page with `limit=20`.\n- Live reads cover TikTok, Meta, Google, OpenAI and Reddit.\n- The rolled-up `status` is not re-derived by a live read.\n\n### TikTok live reads\n\nOn TikTok the same live read also returns the ad group's applied `optimizationGoal` and `billingEvent`, as TikTok's adgroup/get reports them. So you can verify the goal TikTok applied rather than the one you requested.\n\nIt also returns `nativeSettings`: a fixed subset of TikTok's own adgroup/get record for the ad group, with TikTok's own values, read in that same call. It covers budget, budget_mode, schedule, placements, locations, ages, gender, languages, interests, actions, audiences and exclusions, plus the advertiser's currency and timezone.\n\nTikTok's `schedule_start_time` / `schedule_end_time` are UTC wall clocks (\"YYYY-MM-DD HH:MM:SS\", no offset); Ads Manager displays them in `advertiser_timezone`.\n\n`configReadAt` says when it was read. It is null on every row whose native settings were not read now, so never treat a null as a match.\n\nThese are read, not retained create payloads, and are not stored.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Account ID"},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"Platform ad account id (Meta act_<n>). Lists every synced ad set of that ad account; no campaignId needed."},{"name":"campaignId","in":"query","schema":{"type":"string"},"description":"Platform campaign ID"},{"name":"adSetId","in":"query","schema":{"type":"string"},"description":"Platform ad set ID"},{"name":"platform","in":"query","schema":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit"]}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/AdStatus"},"description":"Filter by the ad set's stored `status`, the value each row returns. A live read does not change it. Rows whose `status` is null match no filter."},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":500}},{"$ref":"#/components/parameters/LiveStatusRead"}],"responses":{"200":{"description":"Ad sets","content":{"application/json":{"schema":{"type":"object","properties":{"adSets":{"type":"array","items":{"type":"object","properties":{"platformAdSetId":{"type":"string"},"platform":{"type":"string"},"adSetName":{"type":["string","null"]},"status":{"type":["string","null"],"description":"Stored ad set status (active, paused, pending_review, rejected, completed, cancelled, error), as last synced. The `status` filter matches it."},"platformAdSetStatus":{"type":["string","null"],"description":"Raw platform ad set status. On TikTok the ad group's own switch `operation_status` (ENABLE / DISABLE), independent of its campaign. On Meta and Reddit the ad set's `effective_status` (e.g. CAMPAIGN_PAUSED)."},"platformCampaignId":{"type":["string","null"]},"platformAdAccountId":{"type":"string"},"accountId":{"type":["string","null"]},"profileId":{"type":"string","description":"Profile the row belongs to: the profile of its owning connection (`accountId`); when that connection no longer exists, the requested profile (`profileId` filter) that reaches the row ad account, else the profile of the oldest connection of the row owner that reaches it."},"currency":{"type":["string","null"]},"budget":{"type":["object","null"],"properties":{"amount":{"type":"number"},"type":{"type":"string","enum":["daily","lifetime"]},"daily":{"type":"number","description":"LinkedIn and X only. The daily budget (LinkedIn: the campaign's `dailyBudget`; X: the line item's `daily_budget_amount_local_micro`). Both allow a daily AND a lifetime budget together, which `amount`/`type` cannot express (daily wins there); read `daily` and `lifetime` to see both."},"lifetime":{"type":"number","description":"LinkedIn and X only. The lifetime total (LinkedIn: the campaign's `totalBudget`; X: the line item's `total_budget_amount_local_micro`), readable even when a daily budget is also set."},"pacing":{"type":"string","description":"LinkedIn only. The campaign's `pacingStrategy`: how fast LinkedIn may spend the budget. Typically LINEAR or ACCELERATED; the list is open."}}},"schedule":{"type":["object","null"],"description":"The ad set's own flight dates, as synced from the platform. On LinkedIn this is the campaign's `runSchedule`. Null when the platform reports none.","properties":{"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time","description":"Absent when the ad set runs until it is stopped."}}},"targeting":{"type":["object","null"],"additionalProperties":true,"description":"The ad set's audience as the platform reported it at the last sync, in the platform's own shape. Every platform. null only for an ad set not re-synced yet, or when the targeting read failed on every sync so far (a failed read keeps the last stored value).\n\n- Meta: the ad set's `targeting` verbatim (snake_case: geo_locations, age_min, custom_audiences, flexible_spec, ...), so it can be read, edited and sent back as is.\n- LinkedIn: `include` and `exclude` (below) are the campaign's `targetingCriteria` verbatim, not reconstructed from our normalized targeting spec.\n- TikTok: the ad group's targeting fields from adgroup/get, verbatim (placement_type, placements, location_ids, age_groups, gender, languages, interest_category_ids, actions, audience_ids, excluded_audience_ids, operating_systems, ...). Only fields TikTok returned are present.\n- Google: `campaignCriteria` (LOCATION, LANGUAGE, PROXIMITY, DEVICE, AGE_RANGE, GENDER, USER_LIST, INCOME_RANGE, PARENTAL_STATUS) and `adGroupCriteria` (AGE_RANGE, GENDER, USER_LIST, USER_INTEREST, INCOME_RANGE, PARENTAL_STATUS), each a Google criterion verbatim.\n- Google criteria are camelCase: resourceName, type, negative, bidModifier and the payload its type sets (for example `location.geoTargetConstant`). Most targeting lives on the campaign, so every ad group of a campaign carries the same `campaignCriteria`. Keywords are excluded (own endpoints). Synced on Google's slower keyword cycle.\n- Pinterest: the ad group's `targeting_spec` verbatim (GEO, AGE_BUCKET, GENDER, INTEREST, AUDIENCE_INCLUDE, LOCALE, ...).\n- X: `targeting_criteria`, the line item's criteria as X lists them (targeting_type, targeting_value, operator_type, name), the same shape X's batch create takes.\n- OpenAI: the campaign's `targeting` (OpenAI targets at the campaign), plus the ad group's `context_hints` when it has any.\n","properties":{"include":{"type":"object","description":"LinkedIn `targetingCriteria.include`, verbatim (an `and` of `or` facet clauses)."},"exclude":{"type":"object","description":"LinkedIn `targetingCriteria.exclude`, verbatim. Absent when the campaign excludes nothing."},"audienceExpansionEnabled":{"type":"boolean","description":"LinkedIn audience expansion: whether LinkedIn may also serve to members similar to the criteria."},"offsiteDeliveryEnabled":{"type":"boolean","description":"Whether the campaign may deliver on the LinkedIn Audience Network, off LinkedIn itself."}}},"isExternal":{"type":["boolean","null"]},"platformCreatedAt":{"type":["string","null"],"format":"date-time"},"statusReadAt":{"type":["string","null"],"format":"date-time","description":"Only with `live=true`. When `platformAdSetStatus` was read from the platform; null when this row was not read live."},"optimizationGoal":{"type":["string","null"],"description":"The ad set's optimization goal as last synced, in the platform's own enum:\n\n- Meta: `optimization_goal` (for example OFFSITE_CONVERSIONS or LINK_CLICKS).\n- TikTok: `optimization_goal`. With `live=true`, rows read live carry it exactly as TikTok's adgroup/get returns it now (for example ENGAGED_VIEW, ENGAGED_VIEW_FIFTEEN, CLICK, CONVERT).\n- Pinterest: the conversion event of `optimization_goal_metadata` (for example CHECKOUT).\n- X: the line item `goal`.\n- OpenAI: the campaign `bidding_type`.\n- Google: always null (no per-ad-group optimization goal)."},"billingEvent":{"type":["string","null"],"description":"The ad set's billing event as last synced, in the platform's own enum: Meta `billing_event`, TikTok `billing_event`, Pinterest `billable_event`, X `pay_by`, OpenAI `bidding_config.billing_event_type`.\n\n- Google: always null (it reports none per ad group).\n- TikTok with `live=true`: rows read live carry the ad group's `billing_event` exactly as TikTok's adgroup/get returns it now (for example CPV, CPC, OCPM)."},"bidStrategy":{"type":["string","null"],"description":"The bid strategy as last synced, in Meta's vocabulary (LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS) on every platform that has an equivalent.\n\n- **Meta:** under a campaign budget, this is the campaign's strategy.\n- **Mapped from:** TikTok bid_type / deep_bid_type, Pinterest AUTOMATIC_BID / MAX_BID / TARGET_AVG, X AUTO / MAX / TARGET, OpenAI Maximize Results / a max bid.\n- **Google:** bids at the campaign, so an ad group carries its campaign's strategy. One without a Meta equivalent (MANUAL_CPC, TARGET_IMPRESSION_SHARE, or a portfolio strategy's type such as TARGET_CPA) keeps Google's own name.\n- **LinkedIn:** null."},"bidAmount":{"type":["number","null"],"description":"Bid cap or cost target in whole units of `currency`, as last synced. Null when the strategy has none (automatic bidding, ROAS targets, a Google portfolio strategy). On Google a campaign target CPA, a Maximize clicks ceiling, the ad group's own target CPA override, or its CPC bid under MANUAL_CPC."},"promotedObject":{"type":["object","null"],"additionalProperties":true,"description":"Meta only. The ad set's `promoted_object` verbatim (snake_case, for example pixel_id + custom_event_type, page_id, application_id), as last synced from its most recent ad. Null on other platforms and on an ad set with no ad yet; GET /v1/ads/accounts/live reads it live for every ad set."},"nativeSettings":{"type":"object","additionalProperties":true,"description":"TikTok only, only with `live=true` and only on rows read live. A fixed subset of TikTok's adgroup/get record, not the whole record (snake_case, with TikTok's own names, enums and values). A field TikTok does not return is absent.\n\n**Fields**: adgroup_id, campaign_id, operation_status, optimization_goal, optimization_event, billing_event, bid_type, bid_price, budget, budget_mode, pacing, schedule_type, schedule_start_time, schedule_end_time, dayparting, placement_type, placements, location_ids, age_groups, gender, languages, interest_category_ids, interest_keyword_ids, actions, audience_ids, excluded_audience_ids, operating_systems, frequency, frequency_schedule, smart_audience_enabled, smart_interest_behavior_enabled.\n\nPlus advertiser_currency and advertiser_timezone from TikTok's advertiser/info.\n\n- schedule_start_time and schedule_end_time are UTC wall clocks (YYYY-MM-DD HH:MM:SS).\n- location_ids holds TikTok's native location ids (GeoNames ids for countries). GET /v1/ads/targeting/search?dimension=geo returns them as `platformId` on country results."},"configReadAt":{"type":["string","null"],"format":"date-time","description":"Only with `live=true`. When `nativeSettings` was read from the platform. Null on every row whose native settings were not read now (row past the cap, failed read, or a platform without a native read)."}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads access required (Ads add-on on legacy plans, included on usage-based plans)."}}},"post":{"x-resource-group":"ads","operationId":"createAdSet","tags":["Ad Campaigns"],"x-platforms":["google","reddit"],"summary":"Create a standalone ad group","description":"Creates an empty ad group under an existing campaign, ready for ads to be added later.\n\nThe ad group is created WITHOUT an ad (Google Ads compliance row C.190). Ads join it later via `adSetId` on POST /v1/ads/create. Supports Google Ads and Reddit Ads; every other platform returns 501.\n\n**Google Ads** (`platform: google`)\n\n- The ad group type follows the campaign: a standard ad group under a Search or Display campaign, a Demand Gen ad group under a Demand Gen campaign.\n- On a Demand Gen campaign the ad group is always created PAUSED, and `maxCpc` or `status: ACTIVE` returns 400 (Demand Gen bids at the campaign).\n- `targeting` sets a Demand Gen ad group's locations and languages (`countries`, `regions`, `cities`, `zips`, `metros`, `languages`), created atomically with the ad group. Without it the ad group serves worldwide.\n- `targeting` returns 400 for any other targeting field, and on campaigns that keep geo on the campaign: Search, Display, and Demand Gen campaigns migrated from Discovery. Edit those with PUT /v1/ads/campaigns/{campaignId}/targeting.\n- Any other campaign type returns 400 (Performance Max has asset groups instead of ad groups).\n- A campaign that is not in the ad account, or was removed, returns 404.\n\n**Reddit Ads** (`platform: reddit`)\n\n- `adAccountId` (the Reddit ad account id) is required and must be a selected ad account of the connection (403 otherwise).\n- When the campaign has no campaign budget, send `budgetAmount` + `budgetType` (a lifetime budget needs `endDate`).\n- The ad group is optimized for the campaign's objective. `promotedObject.customEventType` is required on a conversions campaign, and the pixel must have received that event, else 422.\n- It bids with `bidStrategy`/`bidAmount` like POST /v1/ads/create.\n- Under campaign budget optimization the ad group takes the campaign's bid, goal type, optimization event and pixel, and bid fields return 400.\n- The ad group must start no earlier than a future campaign start and end no later than the campaign end (400 otherwise).\n- `targeting` takes the same targeting object as the other ad endpoints (no geo defaults to the US).\n- A campaign of another ad account returns 404, a Reddit Max campaign 422.\n- `maxCpc` and `customerId` are Google only (400 on Reddit), and the other Reddit fields return 400 on Google.\n\n### After creation\n\nCreated `PAUSED` unless `status: ACTIVE`. The new ad group has no ad yet, so it will not appear in GET /v1/ads/tree (built purely from `ads` rows) until one is added. Use GET /v1/ads/ad-sets to see it in the meantime.\n\nIt can be read, edited and deleted through `/v1/ads/ad-sets/{adSetId}` right away (targeting, schedule, name, `status`, `budget` and bid fields). A budget on an ad group that spends its campaign budget returns 422.\n\n**Idempotency:** send an `Idempotency-Key` header to make retries safe.\n","security":[{"bearerAuth":[]}],"parameters":[{"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.\n\n- Same key + same body: replays the original response.\n- Same key + different body: 422.\n- Key still processing: 409.\n\nOnly 2xx responses are stored, so a request that failed with a 4xx can be retried with a corrected body under the SAME key.\n"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","platform","campaignId","name"],"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id owning the Google Ads or Reddit Ads connection."},"platform":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit"],"description":"\"google\" and \"reddit\" are implemented; every other value returns 501."},"campaignId":{"type":"string","description":"Platform campaign ID the ad group is created under (numeric on Google)."},"name":{"type":"string","minLength":1,"maxLength":255},"status":{"type":"string","enum":["ACTIVE","PAUSED"],"default":"PAUSED"},"maxCpc":{"type":"number","exclusiveMinimum":0,"description":"Max CPC of the new ad group, in the account's currency units. Send it when the campaign uses Manual CPC: Google gives an ad group without one a 0.01 bid."},"adAccountId":{"type":"string","description":"Platform ad account ID: the Google customer ID (digits only, only required when the connection has more than one) or the Reddit ad account id (required)."},"customerId":{"type":"string","deprecated":true,"description":"Google only. Alias of adAccountId, kept for existing callers"},"budgetAmount":{"type":"number","exclusiveMinimum":0,"description":"Reddit only. Budget of the new ad group, in the ad account's currency units. Required when the campaign has no campaign budget; 400 under campaign budget optimization, where the campaign budget funds the ad group."},"budgetType":{"type":"string","enum":["daily","lifetime"],"description":"Reddit only. Sent together with budgetAmount."},"startDate":{"type":"string","description":"Reddit only. ISO 8601 start of the ad group. Defaults to now, or to the campaign start when it is in the future."},"endDate":{"type":"string","description":"Reddit only. ISO 8601 end of the ad group. Defaults to the campaign end."},"targeting":{"allOf":[{"$ref":"#/components/schemas/TargetingSpec"}],"description":"Reddit: the full targeting object. Google: locations and languages only, on a Demand Gen campaign."},"promotedObject":{"type":"object","description":"Reddit only. The pixel and the conversion event the ad group optimizes toward.","properties":{"pixelId":{"type":"string","description":"Reddit pixel id. Defaults to the ad account's first pixel."},"customEventType":{"type":"string","description":"Conversion event (PURCHASE, LEAD, SIGN_UP, ADD_TO_CART, PAGE_VISIT). Required on a conversions campaign."}}},"optimizationGoal":{"type":"string","description":"Reddit only. VIDEO_VIEW_6S (default) or VIDEO_VIEW_15S on a video views campaign."},"bidStrategy":{"type":"string","enum":["LOWEST_COST_WITHOUT_CAP","LOWEST_COST_WITH_BID_CAP","COST_CAP"],"description":"Reddit only. Defaults to LOWEST_COST_WITHOUT_CAP. Not accepted under campaign budget optimization."},"bidAmount":{"type":"number","exclusiveMinimum":0,"description":"Reddit only. Bid cap in currency units, sent with bidStrategy."}}}}}},"responses":{"201":{"description":"Ad group created","content":{"application/json":{"schema":{"type":"object","properties":{"adSetId":{"type":"string","description":"Platform id of the new ad group"},"campaignId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The free live ads limit is reached without a card, or the account is not selected: add a card or select it.","description":"Forbidden. The code says why:\n\n- `ads_allowance_exceeded`: the team has no payment method on file and has reached the 500 free live ads. Add a card to resume.\n- `ad_account_not_selected`: the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"description":"Reddit: the campaign is a Reddit Max campaign, the ad account has no pixel, or the pixel never received the conversion event"},"501":{"description":"Only supported on Google Ads and Reddit Ads"}}}},"/v1/ads/ad-sets/{adSetId}/duplicate":{"post":{"x-resource-group":"ads","operationId":"duplicateAdSet","tags":["Ad Campaigns"],"x-platforms":["meta","tiktok"],"summary":"Duplicate an ad set","description":"Copies an ad set, optionally with its ads and into another campaign, created paused so you can review it before launch.\n\nThe copy is created paused so callers can review before launching.\n`campaignId` retargets the copy into another campaign; omitted = the source's own campaign.\n\n**Meta:** ads and creatives are included by default (`deepCopy: true`).\n\n- The ad set is copied with Meta's `/copies` endpoint, then each of its ads (DELETED and ARCHIVED ones are skipped) into the new ad set.\n- So an ad set with any number of ads copies: Meta refuses a single deep copy of 3 or more objects.\n- `statusOption` applies to the ad set and every ad.\n- If an ad copy fails, the partial ad set copy is deleted and the request fails with Meta's error.\n- A sync discovery starts automatically and runs after the response (`syncAfter: false` to skip). The copy is readable through Zernio once it finishes, usually within a few minutes. Until then, calls that take a copied id return 404, so retry them.\n\nTikTok: the ad group is read and recreated under the campaign with its targeting, bidding,\nbudget and schedule (start reset to now); `deepCopy: true` recreates its ads too (default\nfalse). `startTime`, `endTime` and `renameStrategy` are ignored and `statusOption` must be\nPAUSED or absent. The copy appears on the next discovery sync.\n","security":[{"bearerAuth":[]}],"parameters":[{"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.\n\n- Same key + same body: replays the original response.\n- Same key + different body: 422.\n- Key still processing: 409.\n\nOnly 2xx responses are stored, so a request that failed with a 4xx can be retried with a corrected body under the SAME key.\n"},{"name":"adSetId","in":"path","required":true,"schema":{"type":"string"},"description":"Source platform ad set ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform"],"properties":{"platform":{"type":"string","enum":["facebook","instagram","tiktok"]},"campaignId":{"type":"string","description":"Destination platform campaign id (defaults to the source's campaign)"},"deepCopy":{"type":"boolean","default":true,"description":"Copy child ads + creatives"},"statusOption":{"type":"string","enum":["ACTIVE","PAUSED","INHERITED_FROM_SOURCE"],"default":"PAUSED"},"startTime":{"type":"string","format":"date-time","description":"Reschedule the copy's start (ISO 8601). A value without an offset (`YYYY-MM-DD`, `YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DDTHH:MM:SS`) is read in the ad account timezone."},"endTime":{"type":"string","format":"date-time","description":"Reschedule the copy's end, read like `startTime`; a date-only end runs to 23:59:59 local."},"renameStrategy":{"type":"string","enum":["DEEP_RENAME","ONLY_TOP_LEVEL_RENAME","NO_RENAME"],"description":"Meta's native `rename_strategy` values:\n\n- `DEEP_RENAME`: renames the copied ad set and its copied ads with `renamePrefix` / `renameSuffix`.\n- `ONLY_TOP_LEVEL_RENAME`: renames only the copied ad set; its ads keep their source names.\n- `NO_RENAME`: keeps every source name.\n\nWith no rename option at all, Meta appends its own ` - Copy` suffix. Ignored on TikTok, where `renamePrefix` / `renameSuffix` still apply.\n"},"renamePrefix":{"type":"string","description":"Text prepended to each renamed object's name."},"renameSuffix":{"type":"string","description":"Text appended to each renamed object's name."},"syncAfter":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Ad set duplicated","content":{"application/json":{"schema":{"type":"object","properties":{"copiedAdSetId":{"type":"string","description":"Platform ID of the new ad set"},"copiedAdIds":{"type":"array","items":{"type":"string"},"description":"Platform IDs of the copied ads"},"adIdMap":{"type":"object","additionalProperties":{"type":"string"},"description":"Meta only: source ad ID to copied ad ID. Empty when `deepCopy` is false."},"discovery":{"type":"string","enum":["triggered","skipped","failed"],"description":"The copy exists on the platform in all three cases.\n\n- `triggered`: an ads sync started and runs after this response, so the copy may not be readable through Zernio yet.\n- `skipped`: no sync started, so the copy appears on a later scheduled sync.\n- `failed`: the sync could not start. A sync that errors after the response is not reported here."},"raw":{"type":"object","description":"Platform-native response from the copy (TikTok). Absent on Meta, which returns `adIdMap` instead."}}}}}},"400":{"description":"Invalid input"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The free live ads limit is reached without a card, or the account is not selected: add a card or select it.","description":"Forbidden. Codes:\n\n- `ads_allowance_exceeded`: the team has no payment method on file and has reached the 500 free live ads. Add a card to resume.\n- `ad_account_not_selected`: the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"description":"Source ad set not found"},"429":{"$ref":"#/components/responses/MetaAdAccountWriteLimited"},"501":{"description":"Only supported on Meta (facebook/instagram) and TikTok"}}}},"/v1/ads/{adId}/duplicate":{"post":{"x-resource-group":"ads","operationId":"duplicateAd","tags":["Ad Campaigns"],"x-platforms":["meta"],"summary":"Duplicate an ad","description":"Copies a single Meta ad, optionally into another ad set, created paused so you can review it before launch.\n\nIt duplicates the ad via Meta's native `POST /{ad-id}/copies`. The copy is created paused.\n\n- `adSetId` retargets the copy into another ad set; omitted = the source's own ad set.\n- Accepts the Zernio ad id or the platform ad id.\n- A sync discovery starts automatically and runs after the response (`syncAfter: false` to skip). The copy is readable through Zernio once it finishes, usually within a few minutes. Until then, calls that take a copied id return 404, so retry them.\n\n### Creative settings\n\nCreative settings returned by Meta, including explicit promotion metadata and creativeFeatures, are preserved when the native copy requires a creative rebuild. Metadata Meta does not return cannot be recovered.\n\n### Fallback rebuild\n\nWhen Meta refuses the native copy with its capability error (code 3), which happens for some creatives built by other tools, the ad is rebuilt instead:\n\n1. A new creative from the source's returned spec.\n2. A new ad in the target ad set, carrying the source name, status option, rename options and tracking specs.\n","security":[{"bearerAuth":[]}],"parameters":[{"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.\n\n- Same key + same body: replays the original response.\n- Same key + different body: 422.\n- Key still processing: 409.\n\nOnly 2xx responses are stored, so a request that failed with a 4xx can be retried with a corrected body under the SAME key.\n"},{"name":"adId","in":"path","required":true,"schema":{"type":"string"},"description":"Zernio ad ID or platform ad ID"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"adSetId":{"type":"string","description":"Destination platform ad set id (defaults to the source's ad set)"},"statusOption":{"type":"string","enum":["ACTIVE","PAUSED","INHERITED_FROM_SOURCE"],"default":"PAUSED"},"renameStrategy":{"type":"string","enum":["DEEP_RENAME","ONLY_TOP_LEVEL_RENAME","NO_RENAME"],"description":"Meta's native `rename_strategy` values. An ad has no copied children, so `DEEP_RENAME` and `ONLY_TOP_LEVEL_RENAME` both rename the copy with `renamePrefix` / `renameSuffix`, and `NO_RENAME` keeps the source name. With no rename option at all, Meta appends its own ` - Copy` suffix."},"renamePrefix":{"type":"string","description":"Text prepended to the copy's name."},"renameSuffix":{"type":"string","description":"Text appended to the copy's name."},"syncAfter":{"type":"boolean","default":true},"reuseSourceCreative":{"type":"boolean","default":false,"description":"Point the copy at the source ad's creative object instead of copying it. The copy keeps the same Facebook post and Instagram media, their existing likes, comments and shares, and the full creative setup (text variations included).\n\nThis is what Ads Manager's \"show existing reactions, comments and shares\" does; Meta's native copy always publishes new posts.\n\nA creative belongs to one ad account, so `adSetId` must be in the source ad's account. 400 when the source ad has no creative yet.\n"}}}}}},"responses":{"200":{"description":"Ad duplicated","content":{"application/json":{"schema":{"type":"object","properties":{"copiedAdId":{"type":"string","description":"Platform ID of the new ad"},"discovery":{"type":"string","enum":["triggered","skipped","failed"],"description":"The copy exists on the platform in all three cases.\n\n- `triggered`: an ads sync started and runs after this response, so the copy may not be readable through Zernio yet.\n- `skipped`: no sync started, so the copy appears on a later scheduled sync.\n- `failed`: the sync could not start. A sync that errors after the response is not reported here."},"raw":{"type":"object"}}}}}},"400":{"description":"Invalid input"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The free live ads limit is reached without a card, or the account is not selected: add a card or select it.","description":"Forbidden. Two codes:\n\n- `ads_allowance_exceeded`: the team has no payment method on file and has reached the 500 free live ads. Add a card to resume.\n- `ad_account_not_selected`: the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"description":"Ad not found"},"409":{"x-summary":"Several active connections reach this ad account, so the target is ambiguous: keep only one connected for this key.","description":"Several active connections on the API key's profiles reach the ad account of this ad (code `ambiguous_account`), so the connection to act with is ambiguous. Keep one of them connected or move the others to a profile this key cannot access."},"429":{"$ref":"#/components/responses/MetaAdAccountWriteLimited"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/ad-sets/{adSetId}":{"get":{"x-resource-group":"ads","operationId":"getAdSetDetails","tags":["Ad Campaigns"],"x-platforms":["meta"],"summary":"Get live ad-set details","description":"Shows a Meta ad set's current settings straight from Meta, including its learning phase, budget, schedule and targeting.\n\nThe ad set is read live from Meta and returned verbatim. The default projection includes:\n\n- `learning_stage_info`: learning-phase status, LEARNING / SUCCESS / FAIL / WAIVING. Meta omits its `status` key on paused ad sets.\n- delivery settings, budgets and schedule\n- dayparting (`adset_schedule`, `pacing_type`)\n- targeting\n\n`fields` is a raw-passthrough override; unknown fields return Meta's 400 verbatim.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adSetId","in":"path","required":true,"schema":{"type":"string"},"description":"Meta ad set id (platformAdSetId)."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."},{"name":"fields","in":"query","schema":{"type":"string","example":"id,status,ads.limit(100){id,name,status,issues_info}"},"description":"Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers, so a nested edge can be paged explicitly: without a .limit() modifier the expansion runs at the Meta default page size and the tail is dropped silently."}],"responses":{"200":{"description":"The ad set as returned by Meta","content":{"application/json":{"schema":{"type":"object","properties":{"adSet":{"type":"object","description":"Raw Meta ad set; keys are the requested Graph fields."}}}}}},"400":{"description":"Invalid input, or Meta rejected the query; the message carries Meta's error"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}},"put":{"x-resource-group":"ads","operationId":"updateAdSet","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","openai","reddit"],"summary":"Update an ad set","description":"Changes an ad set's settings, such as its budget, bid strategy, status or delivery options. At least one updatable field is required.\n\nUse it for:\n\n- ABO budget updates.\n- Ad-set-scoped pause/resume.\n- Bid-strategy edits.\n- Meta value-rule-set attach/detach.\n- Meta beneficiary and payer: `dsaBeneficiary` / `dsaPayor` for the EU, `regionalRegulatedCategories` / `regionalRegulationIdentities` for the regional regimes.\n- Meta-only post-launch delivery settings via `platformSpecificData`.\n\n### Value rule sets (Meta only)\n\nSee `/v1/ads/value-rule-sets`.\n\n- ATTACH or REPLACE: send `valueRuleSetId`. Attachment is driven by the id's presence, so `valueRulesApplied: true` is optional. Sending a different id replaces the previous association; there is no separate replace call.\n- DETACH: send `valueRulesApplied: false` and OMIT `valueRuleSetId`.\n- Sending `valueRulesApplied: false` TOGETHER with `valueRuleSetId` returns 400 `mutually_exclusive_fields`.\n- Eligibility: only ad sets on `LOWEST_COST_WITHOUT_CAP` or `COST_CAP`. Meta rejects the rest server-side.\n- Read back with `GET /v1/ads/ad-sets/{adSetId}?fields=value_rule_set_id`. Meta does not document `value_rules_applied` as a readable ad-set field, so the boolean cannot be read back.\n\nThe `mutually_exclusive_fields` error is deliberate. Meta attaches the rule set whenever `value_rule_set_id` is present, even with `value_rules_applied` false, so echoing stored state while asking to detach would silently keep the bid adjustments live.\n\n### Bid strategy compatibility (per Meta's spec)\n\n- `LOWEST_COST_WITHOUT_CAP`: no `bidAmount`, no `roasAverageFloor`.\n- `LOWEST_COST_WITH_BID_CAP` / `COST_CAP`: `bidAmount` REQUIRED (whole currency units).\n- `LOWEST_COST_WITH_MIN_ROAS`: `roasAverageFloor` REQUIRED (decimal multiplier, e.g. 2.0 = 2.0x ROAS).\n\nMeta only: send `bidAmount` WITHOUT `bidStrategy` to change the cap amount on an ad set whose strategy (its own, or the campaign's under CBO) is COST_CAP / LOWEST_COST_WITH_BID_CAP, leaving the strategy untouched.\n\nSend `roasAverageFloor` WITHOUT `bidStrategy` the same way to change the floor of a LOWEST_COST_WITH_MIN_ROAS ad set. Either field against an incompatible current strategy is a 400.\n\nMeta CBO (the campaign holds the budget): the campaign also holds the bid strategy, so only `bidAmount` or `roasAverageFloor` is written on the ad set. A `bidStrategy` equal to the campaign's is accepted; a different one is a 409 (change it with PUT /v1/ads/campaigns/{campaignId}).\n\n### Delivery settings and budget\n\nDelivery settings are validated by Meta against the campaign objective. Incompatible combinations (e.g. a billingEvent the optimization goal doesn't allow) surface as 400s from Meta.\n\nWhen updating `budget` on an ad set whose campaign holds the budget (CBO), the response is 409 with code `invalid_field_value`. Send it to PUT /v1/ads/campaigns/{campaignId} instead.\n\n### Status\n\n`status` behaves exactly as PUT /v1/ads/ad-sets/{adSetId}/status describes. Only the ad set's own switch is written and its ads keep theirs. `statusUpdated` / `statusSkipped` report whether that switch was written or a live read showed it already in place.\n\n### Placements and targeting (Meta only)\n\n`placements` and `targeting` take the same shapes as POST /v1/ads/create. Meta replaces an ad set's targeting wholesale, so Zernio reads the live targeting first, changes only what the request names and writes the merged spec back.\n\nCustom audiences, geo, age, interest groups and `targeting_automation` you do not send are kept.\n\n- `placements` replaces the whole placement set.\n- `placements: null` returns the ad set to automatic placements.\n- Omitting it leaves placements as they are.\n\nOther platforms return 400 for either field before anything in the request is written (use PUT /v1/ads/{adId} with `targeting` where that platform supports it).\n\nThe live read and the `incomeTier` lookup run before any other field is written, so a 502 or 422 from them leaves the ad set unchanged.\n\n### Reddit Ads: budget, name and bidding\n\n- `budget` changes the ad group's amount. An ad group that spends its campaign budget returns 422 (update the campaign instead).\n- Reddit cannot switch a published budget between daily and lifetime, so `budget.type` must match the current one (422 otherwise).\n- `name` renames the ad group.\n\n`bidStrategy` maps to the ad group's `bid_strategy`:\n\n- LOWEST_COST_WITHOUT_CAP: automatic bidding (BIDLESS).\n- LOWEST_COST_WITH_BID_CAP: MANUAL_BIDDING with `bidAmount` as the bid.\n- COST_CAP: MAXIMIZE_VOLUME with `bidAmount` as the cap.\n- LOWEST_COST_WITH_MIN_ROAS: returns 422.\n\n### Reddit Ads: targeting and schedule\n\n`targeting` (same shape as on create; `placements` is a 400) and `startDate` / `endDate` change the ad group with one PATCH to Reddit. Read the current values with GET /v1/ads/ad-sets/{adSetId}/targeting.\n\nZernio reads the live ad group first and replaces only the targeting groups the request names:\n\n- The included locations (`countries`, `regions`, `metros`, `cities`, `zips`) are one list on Reddit, so sending any of them replaces all included locations.\n- Devices, platforms, carriers and automated expansion set in Reddit Ads Manager are kept.\n\nThe schedule is checked against the campaign before anything in the request is written. Each of these returns 400 naming `startDate` or `endDate`:\n\n- The ad group starts before a campaign that starts in the future.\n- The ad group ends after the campaign's end.\n- Under campaign budget optimization, it must end by the campaign end (and has no end date when the campaign has none).\n\nZernio never resends the PATCH on its own, so after a 5xx read the ad group back before retrying.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adSetId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform ad set ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform"],"properties":{"platform":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit"]},"budget":{"type":"object","description":"Omit if not updating budget","properties":{"amount":{"type":"number"},"type":{"type":"string","enum":["daily","lifetime"]}}},"status":{"type":"string","enum":["active","paused"],"description":"Writes the ad set's own on/off switch (Meta: `configured_status`; X: the line item's `entity_status` ACTIVE / PAUSED), whatever delivery status its ads report. Omit if not toggling delivery state."},"name":{"type":"string","maxLength":255,"description":"Rename the ad set. At least one of budget/status/bidStrategy/name is required.\n\nSupported on Meta, Google (the ad group), TikTok, LinkedIn (the campaign), Pinterest, X (the line item `name`), OpenAI and Reddit. Platforms without a rename return 501.\n\nThe new name is stored right away, so GET /v1/ads/ad-sets and GET /v1/ads/tree return it without a sync."},"bidStrategy":{"allOf":[{"$ref":"#/components/schemas/BidStrategy"}],"description":"Ad-set-level bid strategy. Overrides the campaign-level default.\n\n- **Meta** (facebook, instagram): supported.\n- **TikTok:** the Meta-style enum is mapped to bid_type / bid_price / deep_bid_type automatically.\n- **OpenAI:** LOWEST_COST_WITH_BID_CAP and COST_CAP both map to the ad group's `bidding_config.max_bid_micros` (one knob covers both). LOWEST_COST_WITH_MIN_ROAS is rejected with 422 (no ROAS-based bidding).\n- **X:** writes the line item's `bid_strategy`: LOWEST_COST_WITHOUT_CAP = AUTO, LOWEST_COST_WITH_BID_CAP = MAX, COST_CAP = TARGET, with `bidAmount` as `bid_amount_local_micro`. LOWEST_COST_WITH_MIN_ROAS is rejected with 422.\n- **X objectives:** X decides which strategy the objective allows (TARGET only on REACH, FOLLOWERS and WEBSITE_CLICKS; MAX not on REACH or FOLLOWERS).\n- **Reddit:** see the mapping in the description above (LOWEST_COST_WITH_MIN_ROAS returns 422).\n- **Others** (linkedin, pinterest, google): 501 Not Implemented when bidStrategy is set.\n"},"dsaBeneficiary":{"type":"string","minLength":1,"maxLength":100,"description":"Meta only (400 elsewhere, before anything in the request is written). Writes the ad set's `dsa_beneficiary`, the legal entity that benefits from its ads. Same field and limits as `dsaBeneficiary` on POST /v1/ads/create. Only the fields you send are written.\n\nThis is the EU DSA field. For regional regimes (Brazil, Malaysia, Thailand, Australia, Singapore, Taiwan, India) use `regionalRegulatedCategories` and `regionalRegulationIdentities` instead.\n\nRead it back with GET /v1/ads/ad-sets/{adSetId}?accountId={accountId}&fields=dsa_beneficiary,dsa_payor.\n"},"dsaPayor":{"type":"string","minLength":1,"maxLength":100,"description":"Meta only (400 elsewhere, before anything in the request is written). Writes the ad\nset's `dsa_payor`, the legal entity that pays for its ads, same field and limits as\n`dsaPayor` on POST /v1/ads/create. Can differ from `dsaBeneficiary`.\n"},"regionalRegulatedCategories":{"type":"array","items":{"type":"string","minLength":1},"description":"Meta only (400 elsewhere, before anything in the request is written). Writes the ad\nset's `regional_regulated_categories`, same values as on POST /v1/ads/create\n(AUSTRALIA_FINSERV, AUSTRALIA_UNIVERSAL, BRAZIL_REGULATION, INDIA_FINSERV,\nMALAYSIA_UNIVERSAL, SINGAPORE_UNIVERSAL, TAIWAN_FINSERV, TAIWAN_UNIVERSAL,\nTHAILAND_UNIVERSAL). Send it with `regionalRegulationIdentities`. An empty array is a 400.\n"},"regionalRegulationIdentities":{"type":"object","additionalProperties":{"type":["string","integer"]},"description":"Meta only (400 elsewhere, before anything in the request is written). Writes the ad set's `regional_regulation_identities`: the Verified identity IDs of the beneficiary and payer for each declared category.\n\n- Same keys and validation as on POST /v1/ads/create (for example `universal_beneficiary` / `universal_payer` for BRAZIL_REGULATION, MALAYSIA_UNIVERSAL and THAILAND_UNIVERSAL).\n- Send each ID as a string of digits; an empty object is a 400.\n- When Meta refuses the ad set for a missing verified advertiser, the 400 `platform_api_error` names the expected keys in `details.expectedIdentityKeys`, as on create.\n\nRead both back with GET /v1/ads/ad-sets/{adSetId}?accountId={accountId}&fields=regional_regulated_categories,regional_regulation_identities.\n"},"smartTargeting":{"type":"object","description":"TikTok only (a 400 elsewhere). TikTok Smart Targeting on the ad group: `audience` is TikTok's `smart_audience_enabled`, `interestsBehaviors` its `smart_interest_behavior_enabled`. When on, TikTok may deliver beyond the selected audiences or interests.\n\nAvailable on Video views, Traffic, Lead generation, App install, Web conversion and Community interaction.\n\nOnly the flags you send are written. An unwritten flag reads back null in `nativeSettings`, so send `false` explicitly to be able to verify it is off. Applied with TikTok's adgroup/update; read it back with GET /v1/ads/ad-sets?adSetId=...&live=true.\n","properties":{"audience":{"type":"boolean","description":"TikTok smart_audience_enabled."},"interestsBehaviors":{"type":"boolean","description":"TikTok smart_interest_behavior_enabled."}}},"placements":{"type":["object","null"],"description":"Meta only (400 elsewhere). Manual placements, with the same object and enums as `placements` on POST /v1/ads/create.\n\n- **Object:** REPLACES the ad set's current placement set (`publisher_platforms`, every `*_positions` list and `device_platforms`). A position list you leave out is removed. An object with no non-empty list is a 400 (send `null` instead).\n- **`null`:** removes every placement key, so Meta returns to automatic (Advantage+) placements.\n- **Omitted:** placements are left untouched.\n\nMeta enforces co-selection rules (e.g. a position needs its publisher platform) and its error is returned as is. Meta may also reject `null` or a narrower set when an ad's creative uses per-placement asset customization (`placementAssets`).\n\nCannot be combined with `targeting.placements` (400).\n","properties":{"publisherPlatforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","threads","messenger","audience_network","whatsapp"]}},"facebookPositions":{"type":"array","items":{"type":"string","enum":["feed","right_hand_column","marketplace","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"]}}}},"startDate":{"type":"string","description":"Reddit only: the ad group's new start_time, ISO 8601. A value without an offset (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS`) is read in the ad account timezone.\n\nIt cannot be earlier than the start of a campaign that starts in the future, nor at or after the ad group's end (400, `param: startDate`).\n\nEvery other platform ignores it (nothing is written and no error is returned, so a body that also sends `status` still applies it). Meta takes it in `platformSpecificData.startDate`.\n"},"endDate":{"type":["string","null"],"description":"Reddit only. The ad group's new end_time, ISO 8601, read in the ad account timezone when it has no offset; a date alone means the end of that day. `null` removes the end date so the ad group runs continuously.\n\nEvery other platform ignores it: nothing is written and no error is returned, so a body that also sends `status` still applies it. Meta takes it in `platformSpecificData.endDate`.\n\nReturns 400 with `param: endDate` when:\n\n- it is not after the start\n- it falls after the campaign's end\n- the campaign uses campaign budget optimization with no end date (Reddit then takes no end date on its ad groups)\n- `null` would outlive a campaign budget campaign that ends\n- `null` is sent for an ad group with a lifetime budget\n"},"targeting":{"allOf":[{"$ref":"#/components/schemas/TargetingSpec"}],"description":"Targeting fields to change. Meta and Reddit (400 elsewhere).\n\n**Reddit** (see the description above):\n\n- `languages` must be among Reddit's ISO 639-1 codes (AR, CS, DA, DE, EL, EN, ES, FI, FR, HU, IT, JA, KO, NL, NO, PL, PT, RO, SV, VI, ZH, any case).\n- Emptying every included location is a 400 with `param: targeting.countries`.\n- Fields Reddit ad groups cannot take (age, income, devices, behaviors, B2B, `places`) return 400 with `param: targeting.<field>`.\n\n**Meta**: same shape as the `targeting` object on POST /v1/ads/create.\n\n- Only the keys you send change. Zernio reads the ad set's live targeting, merges your keys over it and writes the full spec back, so everything else (custom audiences, geo, age, interest groups, `targeting_automation`) is kept.\n- Setting any location replaces every location list. An empty list or `gender: all` clears that key.\n- `incomeTier` is resolved to Meta's income segment first (422 when Meta has none).\n- Fields Meta cannot target (LinkedIn B2B, Google `devices`, Reddit communities and keywords) return 400 with `param: targeting.<field>`.\n- An empty object is a 400, as is a `targeting.placements` object with no non-empty list (`param: targeting.placements`).\n- When the live targeting cannot be read, the request returns 502 and nothing is written.\n"},"bidAmount":{"type":"number","description":"Bid cap in WHOLE currency units (USD: 5 = $5.00; JPY: 100 = ¥100). Required when bidStrategy is LOWEST_COST_WITH_BID_CAP or COST_CAP.\n\nInternally converted to Meta's smallest-denomination integer, or (on OpenAI and X) to micros (× 1,000,000).\n\nMeta only: may be sent alone, WITHOUT bidStrategy, to update the cap amount on an ad set whose parent campaign is COST_CAP or LOWEST_COST_WITH_BID_CAP. The strategy is inherited from the campaign and left untouched.\n"},"roasAverageFloor":{"type":"number","description":"Minimum ROAS as a decimal multiplier (2.0 = 2.0x). Required when bidStrategy is LOWEST_COST_WITH_MIN_ROAS. Sent to Meta as `bid_constraints.roas_average_floor` × 10000. Not supported on OpenAI (422).\n\nMeta only: may be sent alone, WITHOUT bidStrategy, to update the floor on an ad set whose strategy (its own, or the campaign's under CBO) is LOWEST_COST_WITH_MIN_ROAS.\n"},"valueRuleSetId":{"type":"string","pattern":"^\\d+$","description":"Meta only (other platforms return 501). Value rule set to attach to this ad\nset, from `/v1/ads/value-rule-sets`. Sending a different id replaces the\ncurrent association. To DETACH, send `valueRulesApplied: false` and omit\nthis field.\n"},"valueRulesApplied":{"type":"boolean","description":"Meta only (other platforms return 501). `false` DETACHES the ad set's value\nrule set and must be sent WITHOUT `valueRuleSetId`; the combination returns\n400. `true` is optional when attaching, since attachment is driven by\n`valueRuleSetId`, and requires it to be present.\n"},"platformSpecificData":{"type":"object","description":"Platform-specific post-launch delivery settings. The platform is implied by the\n`platform` body param. Meta only; other platforms return 400. Unknown keys are rejected.\n","properties":{"optimizationGoal":{"type":"string","description":"Meta ad-set optimization_goal (e.g. OFFSITE_CONVERSIONS, LANDING_PAGE_VIEWS)."},"billingEvent":{"type":"string","description":"Meta ad-set billing_event (e.g. IMPRESSIONS, LINK_CLICKS, THRUPLAY)."},"startDate":{"type":"string","description":"Ad set start_time (ISO 8601). A value without an offset (`YYYY-MM-DD`, `YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DDTHH:MM:SS`) is read in the ad account timezone."},"endDate":{"type":"string","description":"Ad set end_time (ISO 8601). A value without an offset (`YYYY-MM-DD`, `YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DDTHH:MM:SS`) is read in the ad account timezone."},"dailyMinSpendTarget":{"type":"number","description":"Meta `daily_min_spend_target`: the least this ad set should spend per day, in whole currency units of the ad account.\n\nIt reserves a share of a CAMPAIGN budget for one ad set, so the campaign must use Advantage campaign budget (CBO). On an ad set that owns its budget (ABO) it returns 409; move the budget to the campaign with `PUT /v1/ads/campaigns/{campaignId}` first.\n\nMeta treats it as a target, not a guarantee, and rejects a combined minimum of a campaign's ad sets above the campaign budget.\n\nMutually exclusive with `lifetimeMinSpendTarget` (400): the flavour must match the campaign budget type, so a daily budget takes a daily target.\n\nRead it back with `GET /v1/ads/ad-sets/{adSetId}?fields=daily_min_spend_target`.\n"},"lifetimeMinSpendTarget":{"type":"number","description":"Meta `lifetime_min_spend_target`: the lifetime-budget flavour of\n`dailyMinSpendTarget`, in whole currency units. Send this one when the campaign\nbudget is a lifetime budget. Same rules and same rejections.\n"},"customerLifecycle":{"$ref":"#/components/schemas/MetaCustomerLifecycle"},"adSchedule":{"allOf":[{"$ref":"#/components/schemas/MetaAdSchedule"}],"description":"Replaces the ad set's dayparting (Meta `adset_schedule`, `pacing_type: [\"day_parting\"]`). An empty array removes the schedule (`pacing_type: [\"standard\"]`).\n\nMeta runs a schedule only on a lifetime budget. Before writing anything, Zernio takes `budget.type` from the same request or reads the ad set's budget (or its campaign's under Advantage campaign budget). A daily one is a 400 with `param: platformSpecificData.adSchedule`.\n\nRead it back with `GET /v1/ads/ad-sets/{adSetId}` (`adset_schedule`, `pacing_type`) or as `adSchedule` on `GET /v1/ads/accounts/live`.\n"},"promotedObject":{"type":"object","description":"Meta ad-set promoted_object (same shape as /v1/ads/create). Meta makes promoted_object immutable once the ad set exists, so only `pixelId`, `customEventType`, `customEventStr` (with `customEventType` OTHER), `applicationId` and `productCatalogId` can be sent here.\n\nAny other key (`pageId`, `whatsappPhoneNumber`, `customConversionId`, `objectStoreUrl`, `productSetId`, `offlineConversionDataSetId`) is a 400 with `param: platformSpecificData.promotedObject` and nothing is written. Changing them needs a new ad set (POST /v1/ads/create).\n\nUnknown keys are rejected with 400.\n","properties":{"pixelId":{"type":"string"},"customEventType":{"type":"string"},"customEventStr":{"type":"string","description":"Pixel custom-event name (custom_event_str); requires customEventType OTHER. Same pairing rules as /v1/ads/create."},"pageId":{"type":"string"},"applicationId":{"type":"string"},"objectStoreUrl":{"type":"string"},"customConversionId":{"type":"string"},"productCatalogId":{"type":"string"},"productSetId":{"type":"string"},"offlineConversionDataSetId":{"type":"string"},"whatsappPhoneNumber":{"type":"string"}},"additionalProperties":false}}}}}}}},"responses":{"200":{"description":"Ad set updated","content":{"application/json":{"schema":{"type":"object","properties":{"budget":{"$ref":"#/components/schemas/AdBudget"},"budgetLevel":{"type":"string","enum":["adset"]},"status":{"type":"string","enum":["active","paused"],"description":"As in PUT /v1/ads/ad-sets/{adSetId}/status: delivery derived from the switches read back."},"platformAdSetStatus":{"type":["string","null"],"description":"The ad set's status read back from the platform, as in PUT /v1/ads/ad-sets/{adSetId}/status (Meta and Reddit return the ad set's effective_status); null when it could not be read."},"platformCampaignStatus":{"type":["string","null"]},"statusReadAt":{"type":["string","null"],"format":"date-time"},"statusUpdated":{"type":"integer","enum":[0,1],"description":"1 when the ad set's switch was written."},"statusSkipped":{"type":"integer","enum":[0,1],"description":"1 when a live read showed it already in the requested state."},"statusSkippedReasons":{"type":"array","items":{"type":"string"}},"bidStrategy":{"$ref":"#/components/schemas/BidStrategy"},"bidAmount":{"type":["number","null"]},"roasAverageFloor":{"type":["number","null"]},"platformSpecificData":{"type":"object"},"targeting":{"type":"object","description":"Present when `placements` or `targeting` was sent. The ad set's full targeting as written, in the platform's own vocabulary (Meta or Reddit snake_case). Stored as the ad set's `targeting`.\n\n- Meta stores the same object on its ads.\n- Reddit stores it on its ads in the create vocabulary (`countries`, `communities`, ...), as GET /v1/ads/ad-sets/{adSetId}/targeting returns it."},"startDate":{"type":"string","description":"Reddit: the start_time written, a UTC instant. Present when `startDate` was sent."},"endDate":{"type":["string","null"],"description":"Reddit: the end_time written, a UTC instant, or null when the end date was removed. Present when `endDate` was sent."}}}}}},"400":{"x-summary":"The update is invalid for this platform: fix the placements, targeting or platform-specific fields the message names.","description":"Invalid input, including:\n\n- `placements` on a platform other than Meta, or `targeting` on a platform other than Meta and Reddit.\n- A Reddit `startDate` or `endDate` that is not a date, or a Reddit schedule the campaign does not allow.\n- A targeting field the platform cannot honour.\n- `placements` sent both at the top level and inside `targeting`.\n- A `platformSpecificData.promotedObject` key Meta cannot change on an existing ad set (anything but `pixelId`, `customEventType`, `customEventStr`, `applicationId` and `productCatalogId`)."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The free live ads limit is reached without a card, or the account is not selected: add a card or select it.","description":"Returned with these codes:\n\n- `ads_allowance_exceeded`: the team has no payment method on file and has reached the 500 free live ads. Add a card to resume.\n- `ad_account_not_selected`: the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n- `ad_account_not_selected` fix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection), or use a connection that has it selected.\n"},"404":{"description":"Ad set not found"},"409":{"x-summary":"The ad set rejects this change and nothing changed: set budget or strategy on the campaign, or add an ad first.","description":"Conflict. Nothing is written.\n\n- Campaign is CBO: a budget, or a bidStrategy other than the campaign's (Meta), belongs on /v1/ads/campaigns/{campaignId}.\n- Code `invalid_resource_state`: the ad set has no ads yet and the request sends `status`, `budget`, `bidStrategy`, `bidAmount` or `roasAverageFloor`. These are written through its ads on every platform except Reddit, so add an ad first. A Reddit ad group with no ads takes these fields directly."},"422":{"x-summary":"The bid strategy, Reddit budget or income tier is not supported here: change that field to a supported value.","description":"bidStrategy is LOWEST_COST_WITH_MIN_ROAS on OpenAI or Reddit (unsupported: no ROAS-based bidding), a Reddit budget that the ad group cannot take (campaign budget, or a daily/lifetime switch), or a `targeting.incomeTier` Meta has no income segment for"},"501":{"description":"bidStrategy not supported on the platform (Meta, TikTok, OpenAI and Reddit only)"},"502":{"description":"Meta: the ad set's live targeting could not be read, so the placements or targeting update was not written"}}},"delete":{"x-resource-group":"ads","operationId":"deleteAdSet","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"Delete an ad set","description":"Deletes an ad set and its ads while keeping the campaign, archiving it instead on platforms without a hard delete.\n\nLocally, every Ad document under the ad set is marked\n`status: cancelled`.\n\nDelete is soft on platforms that have no hard delete: LinkedIn moves the\ncampaign to `PENDING_DELETION`, Pinterest and Reddit archive the ad group, and X\nsoft-flags the line item. Google removes the ad group. All remain readable\nfor reporting.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adSetId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform ad set ID"}],"responses":{"200":{"description":"Ad set deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"adCount":{"type":"integer","description":"Local Ad documents marked cancelled (0 for an ad set with no ads)"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"description":"Ad set not found"},"501":{"description":"Operation not supported on this platform"}}}},"/v1/ads/ad-sets/{adSetId}/targeting":{"get":{"x-resource-group":"ads","operationId":"getAdSetTargeting","tags":["Ad Campaigns"],"x-platforms":["reddit"],"summary":"Read a Reddit ad group's targeting and schedule","description":"Shows a Reddit ad group's live targeting and schedule in the same shape PUT /v1/ads/ad-sets/{adSetId} takes, so you can prefill an editor.\n\nIt is read live from Reddit on every call. Reddit only; every other platform returns 501.\n\n### How fields come back\n\n- Location and interest names are resolved with Reddit's targeting taxonomy. When Reddit cannot resolve them the ids stand in as names, and a location that is not a two-letter country is listed under `regions`.\n- Excluded DMAs are listed under `excludedLocations.regions`, since excluded locations have no metro list.\n- Languages come back as lowercase ISO 639-1 codes.\n- Targeting Zernio cannot edit (devices, platforms, carriers, automated expansion) is left out and kept on every edit.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adSetId","in":"path","required":true,"schema":{"type":"string"},"description":"Reddit ad group ID"},{"name":"platform","in":"query","schema":{"type":"string","enum":["reddit"]},"description":"Disambiguates when the same adSetId string exists on more than one connected platform."}],"responses":{"200":{"description":"Current ad group targeting and schedule","content":{"application/json":{"schema":{"type":"object","properties":{"adSetId":{"type":"string"},"targeting":{"allOf":[{"$ref":"#/components/schemas/TargetingSpec"}],"description":"Only the keys the ad group sets. `regions`, `metros`, `cities` and `zips` entries carry `{ key, name }`; `interests` carry `{ id, name }`."},"startDate":{"type":["string","null"],"description":"The ad group's start_time, null when it has none."},"endDate":{"type":["string","null"],"description":"The ad group's end_time, null when it runs continuously."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Ad set not found"},"501":{"description":"The platform has no ad set targeting read (every platform but Reddit)"}}}},"/v1/ads/ad-sets/{adSetId}/status":{"put":{"x-resource-group":"ads","operationId":"updateAdSetStatus","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","openai","reddit","microsoft"],"summary":"Pause or resume a single ad set","description":"Pauses or resumes one ad set without touching its campaign, its sibling ad sets or the switches of its ads.\n\nIt is a thin wrapper over PUT /v1/ads/ad-sets/{adSetId} for callers that only want the status toggle and prefer a symmetric URL to /v1/ads/campaigns/{campaignId}/status.\n\n### What is written\n\nIt writes the ad set's own on/off switch and nothing else, on every platform:\n\n- Meta: `configured_status`\n- TikTok: ad group `operation_status`\n- Google: ad group status\n- LinkedIn: campaign\n- Pinterest: ad group\n- X: line item\n- ChatGPT (OpenAI): ad group\n- Reddit: ad group `configured_status`\n\nIts ads keep their own switches: an ad you paused individually stays paused when the ad set resumes.\n\nThe campaign above is not touched either, so an ad set resumed under a paused campaign reads `status: paused` until the campaign is resumed too. See the Status model in the Ad Campaigns tag.\n\n### Live read, then write\n\nThe ad set's switch is read from the platform first.\n\n- When that live read shows it already in the requested state, nothing is written (`updated: 0`, `skipped: 1`, with the reason).\n- In that case, when the ad set delivers in that state but some of its ads are stored in the other state, those ads (up to 20, at most once every 10 minutes per ad set) are re-read and stored.\n- Otherwise the switch is written (`updated: 1`), read back and stored. The delivery status of its ads (up to 20) is re-read and stored, so an immediate GET returns what the platform now reports.\n\nA stored switch never skips a write, and when the platform cannot be read the write always goes out.\n\nOn Meta and Reddit the check reads the ad set's own switch (`status` / `configured_status`). So a repeated request skips even while `platformAdSetStatus` reads `CAMPAIGN_PAUSED`, `WITH_ISSUES` or `IN_PROCESS`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adSetId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform ad set ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status","platform"],"properties":{"status":{"type":"string","enum":["active","paused"]},"platform":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit","microsoft"]}}}}}},"responses":{"200":{"description":"Ad set status updated","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","paused"],"description":"The ad set's delivery status derived from the switches read back: `paused` when its own switch or its campaign's switch is off. Echoes the request when the platform could not be read."},"platformAdSetStatus":{"type":["string","null"],"description":"The ad set's own switch as read back from the platform (as GET /v1/ads/ad-sets returns it), in raw platform vocabulary. Null when the platform could not be read, which is always the case on X.\n\n- Meta: effective_status.\n- TikTok: ENABLE / DISABLE.\n- Google: ENABLED / PAUSED.\n- LinkedIn and Pinterest: ACTIVE / PAUSED.\n- ChatGPT (OpenAI): status.\n- Reddit: effective_status, such as CAMPAIGN_PAUSED."},"platformCampaignStatus":{"type":["string","null"],"description":"The parent campaign's switch, read in the same call where the platform returns it, otherwise the stored value."},"statusReadAt":{"type":["string","null"],"format":"date-time","description":"When the ad set switch was read back. Null when it could not be read."},"updated":{"type":"integer","enum":[0,1],"description":"1 when the ad set's switch was written."},"skipped":{"type":"integer","enum":[0,1],"description":"1 when a live read showed the ad set already in the requested state, so nothing was written."},"skippedReasons":{"type":"array","items":{"type":"string"},"description":"Why the write was skipped, for example \"Ad set already switched off\"."}}}}}},"400":{"description":"Invalid input"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The free live ads limit is reached without a card, or the account is not selected: add a card or select it.","description":"One of two refusals:\n\n- `ads_allowance_exceeded`: the team has no payment method on file and has reached the 500 free live ads. Add a card to resume.\n- `ad_account_not_selected`: the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"description":"Ad set not found"},"409":{"x-summary":"The ad set has no ads yet and this platform switches status through its ads: add an ad first.","description":"Code `invalid_resource_state`: the ad set has no ads yet, and on this platform its switch is written through its ads. Add an ad first. A Reddit ad group with no ads is switched directly."}}}},"/v1/ads/tree":{"get":{"x-resource-group":"ads","operationId":"getAdTree","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit","microsoft"],"summary":"Get campaign tree","description":"Shows your campaigns with their ad sets and ads nested inside, with spend and results rolled up at every level.\n\n### How it aggregates\n\nUses a two-stage aggregation: ads are grouped into ad sets, then ad sets into campaigns. Metrics are computed over an optional date range, then rolled up from ad level to ad set and campaign levels.\n\n- Pagination is at the campaign level.\n- Ads without a campaign or ad set ID are grouped into synthetic \"Ungrouped\" buckets.\n- If no date range is provided, defaults to the last 90 days. Date range is capped at 730 days max.\n\n### History\n\nWhen an ad account connects, Zernio imports its last 90 days of metrics, so the metrics hold no data for days before that.\n\nWhen `accountId` or `adAccountId` resolves to a Meta ad account, a range reaching further back answers `202` with `backfillPending: true` and the covered part.\n\nThe older days (up to 730 days back) are imported in the background; repeat the request until it returns 200. A request scoped to no Meta account never returns `202`.\n\n### Daily breakdown\n\nPass `timeIncrement=1` to also get a daily breakdown: each node gains a `daily[]` array of per-day metrics (same fields as the aggregated `metrics`) in the same call.\n\nUse `dailyLevel` (`campaign` default, or `adset` / `ad`) to choose which levels carry the series. This replaces calling the tree once per day for per-campaign daily trends.\n\n### Deleted objects stay in the tree\n\nDeleting an ad or a campaign is a soft delete: the Ad documents move to `status: cancelled` and are kept indefinitely. Their historical spend still counts toward the metrics of any date range they fall in. There is no pruning job and no retention window.\n\nPass `status=not_deleted` if your view should hide them, but do that after reading the totals, not before.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PageParam"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Campaigns per page"},{"name":"source","in":"query","schema":{"type":"string","enum":["zernio","all"],"default":"all"},"description":"`all` (default) returns both Zernio-created ads and those discovered from the platform's ad manager. Matches the web UI's default view. Pass `zernio` to restrict to isExternal=false only. Status is NOT filtered by default; use the `status` param for that."},{"name":"platform","in":"query","schema":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit","microsoft"]}},{"name":"status","in":"query","schema":{"anyOf":[{"$ref":"#/components/schemas/AdStatus"},{"type":"string","enum":["not_deleted"]}]},"description":"Filter by derived campaign status (post-aggregation). `not_deleted` keeps every status except `cancelled`."},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"One or more platform ad account IDs to scope the tree to (agency profiles connect a whole Business Manager, but a team usually cares about a subset).\n\n- Comma-separate for multiple (`?adAccountId=act_1,act_2,act_3`); a single value keeps its old shape.\n- Max 50 accounts per request.\n- The plural aliases `adAccountIds` and `platformAdAccountIds` are rejected with a 400, so they cannot silently return the unfiltered fleet."},{"name":"pageId","in":"query","schema":{"type":"string"},"description":"Meta only: Facebook Page ID. Prunes the tree to ads whose creative is backed by this Page: campaigns and ad sets with no ad on the Page drop out, and rolled-up metrics cover only the Page's ads. Mirrors the same filter on /v1/ads and /v1/ads/campaigns."},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Account ID"},{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Profile ID"},{"name":"campaignId","in":"query","schema":{"type":"string"},"description":"Restrict the tree to one or more campaigns by platform campaign id (the id the platform assigns, e.g. Meta's numeric campaign id). Comma-separate up to 100 ids (`?campaignId=123,456`).\n\nFilters the campaign set itself, so it works regardless of account size and pagination. Use it when you already hold campaign ids (e.g. from an `ad.status_changed` webhook) instead of paging the whole tree."},{"name":"updatedSince","in":"query","schema":{"type":"string","format":"date-time"},"description":"Returns only campaigns with a change stored since this time (ISO 8601 with offset, e.g. `2026-09-30T10:00:00Z`). Each matching campaign comes back whole (every ad set and ad).\n\n- A change is a new ad, or a change to any ad's status, review status, name, budget or creative.\n- Metrics are not a change: to refresh numbers, filter with `hasDelivery=true` and a date range instead.\n- Combines with every other filter (with `hasDelivery`/`minSpend` a campaign must match both)."},{"name":"search","in":"query","schema":{"type":"string","maxLength":500},"description":"Case-insensitive substring match on campaign, ad set and ad names (`_`, `%` and spaces match literally), or an exact platform campaign, ad set or ad id.\n\n- A campaign whose name matches returns with all its ad sets and ads.\n- A match on an ad set or ad name returns only the matching branch.\n- Filters the campaign set itself, so `pagination.total` counts only matching campaigns."},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Start of the METRICS date range (YYYY-MM-DD). On its own it affects only the spend/impression numbers overlaid on each node, not which campaigns are returned. Pass `hasDelivery` or `minSpend` to also filter the campaign set to this window. Defaults to 90 days ago."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"End of metrics date range (YYYY-MM-DD). Defaults to today. Max 730-day range."},{"name":"hasDelivery","in":"query","schema":{"type":"boolean"},"description":"Return only campaigns that delivered between `fromDate` and `toDate`: spend above zero, or impressions served at zero spend.\n\nUnlike `status`, which reads a campaign's CURRENT state, this filters on what happened inside the window, so a campaign that spent then and is paused today is still returned. It filters the campaign set itself, so `pagination.total` counts only matching campaigns."},{"name":"minSpend","in":"query","schema":{"type":"number","minimum":0},"description":"Return only campaigns whose spend between `fromDate` and `toDate` reaches this amount. Expressed in each campaign's OWN currency (the `currency` field on the campaign node): spend is stored per ad account in its native currency and one response can span several. Implies `hasDelivery`; `minSpend=0` applies no filter."},{"name":"sort","in":"query","schema":{"type":"string","enum":["newest","oldest","spend_desc","spend_asc"],"default":"newest"},"description":"Campaign-level sort order. `newest` (default) / `oldest` order by the campaign's newest-ad createdAt. `spend_desc` / `spend_asc` order by aggregated spend in the requested date range; campaigns with no spend land at the end."},{"name":"timeIncrement","in":"query","schema":{"type":"integer","enum":[1]},"description":"Set to `1` to also return a daily breakdown (mirrors Meta Insights' `time_increment=1`). Only `1` (daily) is supported. See `dailyLevel` to control which levels carry it.\n\nEach node gains a `daily[]` array of per-day metrics (same fields as the aggregated `metrics`) next to the range total, so you get per-entity daily trends in ONE call instead of one tree call per day.\n\nThe daily series covers the same date range and source data as `metrics`, except `reach` on Meta and TikTok: the range total is the platform's de-duplicated value, so daily reach does not sum to it."},{"name":"dailyLevel","in":"query","schema":{"type":"string","enum":["campaign","adset","ad"],"default":"campaign"},"description":"Which tree levels get the `daily[]` series when `timeIncrement=1`. Ignored when `timeIncrement` is unset.\n\n- `campaign` (default): on campaign nodes only. The common per-campaign-trend case, and the smallest payload.\n- `adset`: on ad sets too.\n- `ad`: on every ad in `ads[]` as well. Heaviest (a long range × up to 100 ads per ad set); scope with `campaignId` to keep responses small."},{"name":"compare","in":"query","schema":{"type":"string","enum":["previous"]},"description":"Set to `previous` to also read the period of the same length that ends the day before `fromDate`. Every campaign, ad set and ad gains `previousMetrics` (same fields as `metrics`) and the response gains `previousRange`, so a table can show the change against the previous period in one call."},{"name":"results","in":"query","schema":{"type":"boolean"},"description":"Set to `true` to add your own results (see [Campaign results](/guides/campaign-results)): every campaign gains `results`, the values you sent for the range plus each formula they allow, and the response gains `resultMetrics` to label them."}],"responses":{"200":{"description":"Nested campaign tree with pagination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdTreeResponse"}}}},"202":{"x-summary":"Historical data is incomplete because the Meta backfill is still pending: retry later for the full history.","description":"Meta only. Historical data is incomplete and backfill remains pending.","headers":{"Retry-After":{"$ref":"#/components/headers/BackfillRetryAfter"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AdTreeResponse"},{"type":"object","required":["backfillPending"],"properties":{"backfillPending":{"type":"boolean","description":"Always true on this response. Part of the requested range is still being backfilled; retry until the request returns 200."}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required: legacy plans need the Ads add-on, and usage-based plans include it by default.","description":"Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans."},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"}}}},"/v1/ads/performance":{"get":{"x-resource-group":"ads","operationId":"listAdsByPerformance","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit","microsoft"],"summary":"Rank ads by performance","description":"Returns an ads account's ads ranked by spend, impressions, clicks, results or ROAS over a date range, each with its creative (type, thumbnail, headline, body, link) and campaign.\n\nUse it to see which creatives perform best. `accountId` is sibling-expanded like `/v1/ads/timeline`.\n\nMoney is ranked by its raw amount, so pass `adAccountId` when the connection's ad accounts bill in different currencies.\n\nA Meta range older than the imported history answers `202` with `backfillPending: true` and the covered part; repeat the request until it returns 200.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Account ID. Sibling-expanded to its linked posting and ads pair. An id the API key cannot reach answers 404."},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"Optional platform-native ad account ID (e.g. Meta `act_…`) to rank one ad account only."},{"name":"fromDate","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Inclusive start of the range (YYYY-MM-DD)."},{"name":"toDate","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Inclusive end of the range (YYYY-MM-DD). Max 730-day range."},{"name":"platform","in":"query","schema":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit","microsoft"]},"description":"Restrict to one platform."},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["spend","impressions","clicks","conversions","roas"],"default":"spend"},"description":"Metric the ads are ranked by, highest first."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"How many ads to return."}],"responses":{"200":{"x-summary":"Ads ranked by `sortBy` are returned, and ads with no delivery in the range are left out.","description":"Ads ranked by `sortBy`. Ads with no delivery in the range are left out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsPerformanceResponse"}}}},"202":{"x-summary":"Historical data is incomplete because the Meta backfill is still pending: retry later for the full history.","description":"Meta only. Historical data is incomplete and backfill remains pending.","headers":{"Retry-After":{"$ref":"#/components/headers/BackfillRetryAfter"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AdsPerformanceResponse"},{"type":"object","required":["backfillPending"],"properties":{"backfillPending":{"type":"boolean","description":"Always true on this response. Retry until the request returns 200."}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required: legacy plans need the Ads add-on, and usage-based plans include it by default.","description":"Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"}}}},"/v1/ads/timeline":{"get":{"x-resource-group":"ads","operationId":"getAdsTimeline","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit","microsoft"],"summary":"Get daily account metrics","description":"Returns an ads account's spend, results and other metrics day by day, ready for a daily performance chart.\n\nThe result is a single time series of daily aggregate metrics across all ads in a SocialAccount: one row per calendar day and currency in the requested range (one row per day unless the account's ad accounts bill in different currencies).\n\nUse this for dashboards that draw a daily-spend or daily-conversions chart, instead of calling `/v1/ads/tree` once per day.\n\n### Parameters\n\n- `accountId` is required. The lookup is sibling-expanded, so passing the `metaads` ID also includes ads under the linked `facebook` / `instagram` posting account (and vice-versa), the same convention as `/v1/ads/tree` and `/v1/ads`.\n- Date range defaults to the last 90 days. Capped at 730 days.\n- With adAccountId set to a Google customer id this is the customer-level performance report (clicks, cost, impressions, conversions, all conversions per day).\n\n### History\n\nWhen an ad account connects, Zernio imports its last 90 days of metrics, so `rows` hold no data for days before that.\n\nWhen `accountId` or `adAccountId` resolves to a Meta ad account, a range reaching further back answers `202` with `backfillPending: true` and the covered part. The older days (up to 730 days back) are imported in the background; repeat the request until it returns 200.\n\nOther platforms never return `202`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Account ID. Sibling-expanded to its linked posting↔ads pair. An id that does not exist or sits on a profile the API key cannot reach answers 404 (code: account_not_found)."},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"Optional platform-native ad account ID (e.g. Meta `act_…`, TikTok advertiser ID). Use when the connection wraps multiple platform ad accounts and the chart should show one only. Note: rows ingested before 2026-05-13 don't carry this column; the recurring 7-day re-sync repopulates them naturally."},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Inclusive start of metrics range (YYYY-MM-DD). Defaults to 90 days ago."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"Inclusive end of metrics range (YYYY-MM-DD). Defaults to today. Max 730-day range."},{"name":"platform","in":"query","schema":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit","microsoft"]},"description":"Restrict to one platform."},{"name":"compare","in":"query","schema":{"type":"string","enum":["previous"]},"description":"Set to `previous` to also return `previousRows` for the period of the same length that ends the day before `fromDate`, with that period as `previousRange`. Needs a `fromDate` (sent or defaulted); `toDate` alone answers 400."}],"responses":{"200":{"x-summary":"A daily time series of aggregate metrics is returned: empty `rows` means no ad activity in the range.","description":"Daily time series of aggregate metrics. Empty `rows` means the account has no ad activity in the range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsTimelineResponse"}}}},"202":{"x-summary":"Historical data is incomplete because the Meta backfill is still pending: retry later for the full history.","description":"Meta only. Historical data is incomplete and backfill remains pending.","headers":{"Retry-After":{"$ref":"#/components/headers/BackfillRetryAfter"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AdsTimelineResponse"},{"type":"object","required":["backfillPending"],"properties":{"backfillPending":{"type":"boolean","description":"Always true on this response. Part of the requested range is still being backfilled; retry until the request returns 200."}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required: legacy plans need the Ads add-on, and usage-based plans include it by default.","description":"Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"}}}},"/v1/ads/{adId}":{"get":{"x-resource-group":"ads","operationId":"getAd","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit","microsoft"],"summary":"Get ad details","description":"Shows one ad with its creative, targeting, status and performance metrics.\n\n### Google Search ads\n\nGoogle Search ads include current creative.headlines, creative.descriptions and creative.finalUrls, preserving pinnedField. Top-level cachedAt and stale report cache freshness. Google mutations invalidate this read.\n\nRSA enrichment requires a stored advertisingChannelType of SEARCH. Ads with an unknown or other channel return their stored details without a Google read. If RSA enrichment fails, the stored ad is returned with HTTP 200 and without cache metadata.\n\n### Accepted ad ids\n\nThe `{adId}` path segment accepts any identifier dialect Zernio indexes for the ad:\n\n- the Zernio internal `_id` (24-char hex)\n- Meta's numeric `platformAdId` (the value shipped in `comment.received` webhooks as `comment.ad.id`)\n- the creative's `effective_object_story_id` (`{pageId}_{postId}` shape, Facebook side)\n- the creative's `effective_instagram_media_id` (Instagram side)\n- an Instagram media id an ad comment arrived on (`comment.platformPostId` of a `comment.received` carrying `comment.ad.id`), including the extra media Meta creates for placement variants\n\nAny of these resolve to the same ad, so the caller doesn't need a translation step.\n\n`creative.creativeFeatures` holds the stored requested settings, which do not confirm platform application.\n\n### Facebook ad dark posts\n\nMeta gives an ad with per-placement assets one extra unpublished post per placement, and comments land on it. Meta exposes no link from that post to its ad.\n\n- When exactly one ad on the Page, created before the dark post, carries the same copy as the post, the dark post id resolves to that ad.\n- Otherwise, when the id is a dark post Zernio has seen comments on and its Page is connected, the response is `ad: null` plus `darkPost`. It carries the Meta Ads account and the ad accounts running ads for that Page.\n\nRead its comments with GET /v1/ads/{adId}/comments using the same id.\n\n### Status freshness\n\n`status`, `configuredStatus`, `platformStatus`, `platformAdSetStatus` and `platformCampaignStatus` are the values Zernio last stored.\n\nBackground sync refreshes them, typically within 15 to 60 minutes (Google up to about 3 hours), and ended or long-paused objects may be refreshed less often.\n\nZernio's own status writes re-read the switches they change. A change made in the platform's own ads manager therefore shows up here only after the next sync.\n\nControllers that act on a switch should pass `live=true`. It reads the switches from the platform now, stores them, and returns `statusReadAt` (null when the read failed and the stored values were returned).\n\nWith `live=true` these are read live:\n\n- the ad's own switch (`configuredStatus`)\n- its delivery status (`status`, `platformStatus`)\n- its ad set and campaign switches (`platformAdSetStatus`, `platformCampaignStatus`)\n- on TikTok, the creative TikTok holds now: `creative.body` (ad text), `creative.callToAction`, `creative.linkUrl` (landing page), `creative.videoId`, `creative.adFormat`, `creative.identityId`, `creative.identityType`, `creative.identityAuthorizedBcId` and, on a Spark ad, `creative.tiktokItemId`.\n\nThe TikTok creative comes from the same TikTok call as the switches. It replaces the stored values in the response only and is never stored. A key TikTok leaves empty keeps its stored value.\n\n### Meta ads that are not synced yet\n\nPass `accountId` with a Meta `platformAdId` to read an ad Zernio has not synced (for example one created in Ads Manager on an ad account reached only through a Facebook connection).\n\nThe ad is read live from Meta and mapped exactly like a synced row: name, `status`, `platformStatus`, `configuredStatus`, `platformAdSetId`, `platformCampaignId`, campaign and ad set names, budgets, and `creative` with its `id`, body, link, image and video.\n\nIt comes back with `synced: false`, no `id` (it has no Zernio row) and `statusReadAt` set to the time of the read. Synced ads answer `synced: true`.\n\nOnly a numeric id takes this path, so dark post ids (`{pageId}_{postId}`) keep the dark post lookup above.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adId","in":"path","required":true,"schema":{"type":"string"},"description":"Zernio `_id` (hex), Meta `platformAdId` (numeric), or one of the creative's effective story/media IDs. See description for details.\n"},{"$ref":"#/components/parameters/LiveStatusRead"},{"$ref":"#/components/parameters/UnsyncedMetaAdAccountId"}],"responses":{"200":{"description":"Ad details","content":{"application/json":{"example":{"ad":{"platform":"google","creative":{"headlines":[{"text":"Social Media API","pinnedField":"HEADLINE_1"},{"text":"Schedule Your Posts"},{"text":"Build With Zernio"}],"descriptions":[{"text":"Connect social accounts with one API.","pinnedField":"DESCRIPTION_1"},{"text":"Build social publishing into your application."}],"finalUrls":["https://zernio.com"]}},"cachedAt":null,"stale":false},"schema":{"type":"object","properties":{"ad":{"$ref":"#/components/schemas/Ad"},"cachedAt":{"type":["string","null"],"format":"date-time","description":"Google RSA details cache timestamp."},"stale":{"type":"boolean","description":"Whether Google RSA details use the last successful cached response."},"statusReadAt":{"type":["string","null"],"format":"date-time","description":"With `live=true`, when the switches were read from the platform; null when the live read failed and the stored values were returned. Always set on an unsynced Meta ad read with `accountId`, the time of that read."},"darkPost":{"type":"object","description":"Only when `{adId}` is a Facebook ad dark post with no resolvable ad (then `ad` is null).","properties":{"platform":{"type":"string","enum":["facebook"]},"platformPostId":{"type":"string","description":"The dark post id, `{pageId}_{postId}`."},"pageId":{"type":"string"},"isDarkPost":{"type":"boolean","description":"Always true."},"adId":{"type":["string","null"],"description":"Always null: Meta exposes no link from a placement dark post to its ad."},"accountId":{"type":["string","null"],"description":"Zernio Meta Ads account id for the Page, null when none is connected."},"facebookAccountId":{"type":"string","description":"Zernio Facebook account id of the Page."},"platformAdAccountIds":{"type":"array","items":{"type":"string"},"description":"Meta ad accounts (`act_...`) with synced ads on this Page."},"firstSeenAt":{"type":"string","format":"date-time"},"lastActivityAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/NotFound"},"501":{"description":"`accountId` names a connection that is not Meta (unsynced ad reads are Meta only)."}}},"put":{"x-resource-group":"ads","operationId":"updateAd","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit","microsoft"],"summary":"Update ad","description":"Changes an ad's status, budget, targeting or creative and applies the change on the platform.\n\nPatch one or more fields on an ad. Status, budget, targeting, and creative changes are propagated to the platform.\n\n### Per-platform support\n\n- **Meta** (Facebook + Instagram): all fields supported.\n- **TikTok**: status, budget, `name` (renames the ad), targeting (via `/v2/adgroup/update/`), and creative (via `/v2/ad/update/` patch-style: `headline` is ignored, `body` becomes `ad_text`).\n- **Google**: see the Google sections below.\n- **LinkedIn**: status, budget, targeting and creative (details below).\n- **Pinterest / X / OpenAI Ads**: status + budget only. Sending `targeting` or `creative` returns 501 with code `feature_not_available`. OpenAI Ads budget is the campaign's spend cap, daily or lifetime (see `budget.type` below).\n- **Reddit Ads**: status, budget, `name` (renames the ad) and targeting (details below).\n\n### Google\n\nSupported: status, budget, and these targeting edits:\n\n- KEYWORD edits via `targeting.keywords` / `targeting.negativeKeywords`\n- DEVICE bid adjustments via `targeting.devices`\n- LOCATION edits via `targeting.locations` (or the equivalent top-level `targeting.countries` / `regions` / `cities` / `zips` / `metros`)\n- LANGUAGE edits via `targeting.languages`\n\nEach list you send becomes the FULL new set of its kind: criteria not in the list are removed. Devices are the exception: Google cannot remove them, so they are switched off with a bid modifier of 0 instead. A kind left out is untouched.\n\nAny other `targeting` field returns 400: Google cannot mutate it post-create without recreating the campaign.\n\nCreative edits are dispatched on the ad's `advertisingChannelType`. Every supported field replaces a whole set; a field you omit is preserved.\n\n- **Search**: top-level `headlines`, `descriptions` and `finalUrls`. Use 3-15 headlines (1-30 characters) and 2-4 descriptions (1-90 characters). Omit an asset to remove it; omit pinnedField on an included asset to unpin it. Updates do not pad or truncate text. The legacy creative fields remain unsupported.\n- **Display**: top-level `headlines` (1-5, no pinnedField, display ads have no pinned positions), `descriptions` (1-5) and `finalUrls`, plus `creative.longHeadline`, `creative.businessName`, `creative.imageUrl` (the landscape marketing image) and `creative.squareImageUrl`.\n- **Performance Max**: top-level `assetGroup`, which swaps asset roles on the ad's asset group. The other creative fields return 422 for this channel, and `assetGroup` returns 422 on any other channel.\n- **Demand Gen**: top-level `demandGen` (see GoogleDemandGenUpdate): creative, channel and audience changes in one atomic Google request. The other creative fields return 422 for this channel.\n\nFor Display, each image URL is uploaded as a new Google asset and the ad is pointed at it.\n\nGoogle assets are immutable, so the previous asset stays in the account's asset library. A new landscape image also updates `creative.assetResourceName` to the new asset, and each replaced image updates its own role in `creative.assets`.\n\nFor Demand Gen, `targeting` takes locations, languages, `locationTargetingType` and `devices`. Locations and languages are written to the ad's ad group, which Demand Gen requires, so they apply to every ad in that ad group. Campaigns migrated from Discovery that still target on the campaign keep being written there.\n\n### LinkedIn\n\n- **Status and budget**: supported.\n- **Targeting**: countries or regions, excludedLocations (countries), the B2B facets, and audience segments. Applied to the LinkedIn Campaign via PARTIAL_UPDATE, and REPLACES the campaign's entire targetingCriteria, not a merge.\n- **Creative**: uploads new media, creates a replacement inline creative on the same campaign, and removes the old one (it is deleted, the ad's `platformAdId` and `creative.creativeId` move to the new creative, and the new creative keeps the old one's held-off state: `DRAFT` stays `DRAFT`).\n- **Name**: updating `name` returns 400 (LinkedIn does not support renaming an ad).\n\n### Reddit Ads\n\n- `budget` goes to the ad's ad group, or to its campaign when the ad group spends a campaign budget. It keeps its daily or lifetime type (422 to switch).\n- `targeting` REPLACES the ad group's whole targeting (geo, communities, conversation keywords, interests, audiences, languages, gender), so it applies to every ad in the ad group.\n- `creative` returns 501: a Reddit ad runs a post, so create a new ad with the new creative instead.\n\n### Google location and language replacement\n\nLocations, languages and devices are campaign-level criteria on Google, so these edits apply to every ad group and ad in the ad's campaign. Send the complete list you want to keep.\n\nZernio diffs it against the campaign's live criteria and sends the removes and the creates in ONE `googleAds:mutate`, so the campaign is never left with a half-applied set. Criteria already in the list keep their criterion ID and history. Excluded (negative) locations are left untouched.\n\n- An empty location list returns 400. A Google campaign with no location criteria targets every country, which is never what \"remove my locations\" means, so omit the field instead.\n- Send either `targeting.locations` or the top-level geo fields, not both: mixing them returns 400.\n\n### Google radius targeting\n\n`customLocations` is editable and is replaced the same way, but as its OWN set. Google models a place (LOCATION) and a point plus radius (PROXIMITY) as different criterion types, so the two are independent:\n\n- Sending `customLocations` replaces every radius and leaves the cities and countries alone.\n- Sending places replaces those and leaves the radius alone.\n- Send `customLocations: []` to drop radius targeting entirely.\n\nA circle you re-send unchanged keeps its criterion ID rather than being removed and recreated.\n\n### Google keyword replacement\n\nThese edits affect the ad's entire ad group, including sibling ads. Positive (`targeting.keywords`) and negative (`targeting.negativeKeywords`) sets are independent: omit a field to leave that set unchanged, or send `[]` to remove every keyword of that kind.\n\nZernio compares each supplied set with Google's live criteria by case-insensitive keyword text and match type. Text comparison does not trim whitespace.\n\nA matching criterion is left untouched, retaining its criterion ID, enabled/paused status, keyword-level bid overrides, labels, and criterion-associated history/statistics. Zernio does not reset its quality score; Google continues to calculate scores and statistics normally.\n\nA bare string or an object without `matchType` means `broad`, not the existing criterion's match type. For example, resending an existing `{ \"text\": \"plumber\", \"matchType\": \"exact\" }` preserves it; sending `\"plumber\"` instead removes that EXACT criterion and requests a BROAD one.\n\nChanging text or match type removes criteria no longer requested and creates any missing criteria. New criteria get new IDs and do not inherit removed criteria's bid overrides, labels, or history. Historical reporting for a removed criterion is not transferred to its replacement.\n\n### Other keyword endpoints\n\n- To add keywords without replacing a set, use [POST /v1/ads/keywords](https://docs.zernio.com/ad-campaigns/add-ad-keywords).\n- Use `PATCH /v1/ads/keywords/{keywordId}` to pause/enable one keyword.\n- Use `DELETE /v1/ads/keywords/{keywordId}` to remove it.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"examples":{"googleRsa":{"summary":"Replace and pin Google RSA text.","value":{"headlines":[{"text":"Social Media API","pinnedField":"HEADLINE_1"},{"text":"Schedule Your Posts"},{"text":"Build With Zernio"}],"descriptions":[{"text":"Connect social accounts and schedule posts with the Zernio API.","pinnedField":"DESCRIPTION_1"},{"text":"Build social publishing into your application."}],"finalUrls":["https://zernio.com"]}},"googlePmaxAssets":{"summary":"Swap the headlines and the landscape image on a Performance Max asset group.","value":{"assetGroup":{"headlines":["Schedule posts","One social API","Build with Zernio"],"images":{"landscape":["https://example.com/new-landscape.png"]}}}},"googleDisplayCreative":{"summary":"Replace the text and the image on a Google Display ad.","value":{"headlines":[{"text":"Schedule posts"},{"text":"One social API"}],"descriptions":[{"text":"Publish and manage social content through one API."}],"creative":{"longHeadline":"Schedule social content from your app with Zernio","imageUrl":"https://example.com/new-landscape.png","squareImageUrl":"https://example.com/new-square.png"}}},"googleDemandGen":{"summary":"Change a Google Demand Gen ad's headlines and square image, and swap its ad group audience.","value":{"demandGen":{"headlines":["Schedule posts","One social API"],"images":{"square":["https://example.com/new-square.png"]},"audience":{"userInterests":["92948"],"genders":["female"]}}}},"metaAssetFeedText":{"summary":"Edit the second of two primary text options on a Meta asset_feed creative, keeping its videos and placement rules.","value":{"creative":{"bodies":["First primary text, unchanged","Second primary text, edited"]}}},"metaCreativeFeatures":{"summary":"Opt a Meta creative out of an Advantage+ enhancement.","value":{"creative":{"creativeFeatures":{"auto_promotion_tag":"OPT_OUT"}}}}},"schema":{"type":"object","properties":{"headlines":{"type":"array","minItems":1,"maxItems":15,"items":{"$ref":"#/components/schemas/GoogleRsaHeadline"},"description":"Google Search and Display only. Replaces the complete headline list. Search takes 3-15, Display 1-5 and rejects pinnedField; the count is checked once the ad's channel is known. No padding or truncation on update."},"descriptions":{"type":"array","minItems":1,"maxItems":5,"items":{"$ref":"#/components/schemas/GoogleRsaDescription"},"description":"Google Search and Display only. Replaces the complete description list. Search takes 2-4, Display 1-5 and rejects pinnedField. No padding or truncation on update."},"finalUrls":{"type":"array","minItems":1,"items":{"type":"string","format":"uri"},"description":"Google Search and Display only. Replaces final URLs. Omitted lists stay unchanged. For Performance Max use assetGroup.finalUrl."},"assetGroup":{"allOf":[{"$ref":"#/components/schemas/GooglePmaxAssetGroupUpdate"}],"description":"Google Performance Max only. Replaces whole asset roles on the ad's asset group. Returns 422 on any other platform or channel."},"demandGen":{"allOf":[{"$ref":"#/components/schemas/GoogleDemandGenUpdate"}],"description":"Google Demand Gen only. Returns 422 on any other platform or channel."},"status":{"type":"string","enum":["active","paused"]},"budget":{"type":"object","properties":{"amount":{"type":"number","description":"Minimum varies by platform: TikTok=$20, Pinterest=$5, others=$1"},"type":{"type":"string","enum":["daily","lifetime"],"description":"OpenAI Ads accepts both and sets the campaign's single spend cap, replacing the previous daily or lifetime cap. A daily cap cannot go back to lifetime (422)."}}},"targeting":{"type":"object","description":"Targeting update.\n\n- Meta + TikTok: demographics/interests.\n- Google: keyword and device bid adjustment edits only.\n- LinkedIn: locations, B2B facets, audiences.\n- Pinterest / X: return 501.\n\n**Partial update** on Meta, TikTok and LinkedIn: every targeting setting you do not send is preserved.\n\n- Meta: Advantage+ audience, placements, custom audiences, exclusions, interests, languages.\n- TikTok: languages, interest keywords, devices, behaviours.\n- LinkedIn: skills, member traits, interface locales, and any facet set in Campaign Manager.\n\nA field you send replaces its platform counterpart, and an empty or null value (for example `audienceInclude: []`, `industries: []` or `gender: \"all\"`) clears only that field.\n\nAny location field (countries, regions, cities, zips, ...) replaces the whole included location set; an update with no location keeps the current locations.\n","properties":{"keywords":{"type":"array","description":"Google only. The FULL desired set of positive keywords for the entire ad group. Omit to leave positives unchanged; [] removes all positives. Negatives are independent.\n\n- Entries are strings (BROAD) or { text, matchType } with matchType exact | phrase | broad. An omitted matchType also defaults to BROAD.\n- Matching case-insensitive text AND match type keeps the existing criterion ID, status, bid overrides, labels and history, with no mutation.\n- A changed text or match type uses remove/create, without carrying over the old criterion's attributes or history.\n\nSee Google keyword replacement above for an EXACT-to-BROAD example. Mirrored to GET /v1/ads/keywords immediately.\n","items":{"oneOf":[{"type":"string"},{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":80},"matchType":{"type":"string","enum":["exact","phrase","broad"]}}}]}},"negativeKeywords":{"type":"array","description":"Google only. The FULL desired set of negative keywords for the entire ad group, independent of positives.\n\n- Omit to leave negatives unchanged; [] removes all negatives.\n- Same text/match-type identity and preservation contract as keywords above.\n- Strings and objects without matchType default to BROAD, so resending an EXACT or PHRASE negative as a bare string requests a different criterion.\n- Campaign negatives are separate: manage them with /v1/ads/campaigns/{campaignId}/negative-keywords.\n","items":{"oneOf":[{"type":"string"},{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":80},"matchType":{"type":"string","enum":["exact","phrase","broad"]}}}]}},"devices":{"type":"array","description":"Google only. The FULL new set of device bid modifiers for the campaign. Entries are a device name alone (targeted, bid modifier reset to 1) or { device, bidModifier }.\n\n- A supported device you leave out is switched off, written as a bid modifier of 0. Google never removes a device criterion, so an excluded device reads back as bidModifier 0 rather than disappearing.\n- A set that switches every device off returns 422.\n- Devices depend on the channel: Search campaigns have MOBILE, DESKTOP and TABLET; Display campaigns also have CONNECTED_TV. Sending a device the campaign does not carry returns 422.\n","items":{"oneOf":[{"type":"string","enum":["MOBILE","DESKTOP","TABLET","CONNECTED_TV"]},{"type":"object","required":["device"],"properties":{"device":{"type":"string","enum":["MOBILE","DESKTOP","TABLET","CONNECTED_TV"]},"bidModifier":{"type":"number","minimum":0,"maximum":10,"description":"Google device bid modifier. 0 switches the device off (minus 100%); otherwise 0.1 to 10 (minus 90% to plus 900%). Google rejects any value between 0 and 0.1."}}}]}},"ageMin":{"type":"integer","minimum":13,"maximum":65},"ageMax":{"type":"integer","minimum":13,"maximum":65},"countries":{"type":"array","items":{"type":"string"},"description":"ISO 3166-1 alpha-2 codes. On Google this is the FULL new country set for the campaign (same contract as `locations`); on LinkedIn it replaces the campaign's geo criteria."},"locations":{"description":"Google and LinkedIn. The FULL new location set for the campaign. Bare country-code array, or an object with countries/regions/cities/zips/metros key lists (`key` from GET /v1/ads/targeting/search?dimension=geo). Equivalent to the top-level geo fields; sending both returns 400. Empty returns 400, `customLocations` returns 422.","oneOf":[{"type":"array","items":{"type":"string","description":"ISO 3166-1 alpha-2 country code."}},{"type":"object","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","items":{"type":"object","required":["key"],"properties":{"key":{"type":"string"},"name":{"type":"string"}}}},"zips":{"type":"array","items":{"type":"object","required":["key"],"properties":{"key":{"type":"string"},"name":{"type":"string"}}}},"metros":{"type":"array","items":{"type":"object","required":["key"],"properties":{"key":{"type":"string"},"name":{"type":"string"}}}}}}]},"languages":{"type":"array","items":{"type":"string"},"description":"Google only. The FULL new language set for the campaign, as Google language codes (ISO 639-1, plus variants such as `zh_CN`). An unknown code returns 400."},"interests":{"type":"array","description":"Interest objects from /v1/ads/interests. Each must include id and name.","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"advantage_audience":{"type":"integer","enum":[0,1],"description":"Meta only. Omit to preserve the existing setting on update. 0 = disabled, 1 = enabled."}}},"creative":{"type":"object","description":"Replace or patch the ad's creative. Meta, TikTok, and LinkedIn.\n\n**Meta**: patch-style.\n\n- Pass any subset: omitted fields are preserved from the live creative, including media (`image_hash`/`video_id` reused, no re-upload) and `url_tags`. Sending the full set (`headline`, `body`, `callToAction`, `linkUrl`, `imageUrl`) rebuilds the creative from scratch.\n- Partial patching reads the live `object_story_spec`, which Meta strips on SHARE / page-post / dark post creatives; those return 422 asking for the full set. A `videoUrl`/`videoId` on an image creative is a type change and also needs the full set.\n- Creatives with an `asset_feed_spec` (several text options, placement or language rules) take text, link, tracking and enhancement edits in place. The new creative is built from the live asset feed with the edited text, and every video, image, label and rule is kept.\n- On those, `body`, `headline` and `description` replace the one option of that kind. When the feed has several, send `bodies`, `headlines` or `descriptions` with one text per option, in order. `linkUrl` replaces the feed's only destination link.\n- Image, video and call-to-action changes on asset_feed creatives apply to the story spec (Multiple Text Options creatives). They return 422 when the feed itself holds the images, videos or call-to-action options.\n- The live creative's deprecated `standard_enhancements` setting (Meta subcode 3858504) is never sent back; every other enhancement setting is kept.\n- `existingCreativeId` repoints the ad at a creative from GET /v1/ads/creatives and ignores every other field.\n- Meta creatives are immutable: any change creates a new creative and repoints the ad. The old creative stays on the ad account for historical reporting.\n- `creativeFeatures` is Meta-only. Omitted settings are preserved from the live creative, including on full rebuilds; a supplied creativeFeatures map overrides individual existing keys.\n\n- A `creative` object with no recognised field (`promotion` alone does not count) is a 400 `missing_required_field` when it is the only update, and is ignored (no creative rebuild) next to another updatable field.\n\n**TikTok**: patch-style. Pass any subset.\n\n- `headline` is ignored (no headline slot).\n- `body` becomes the in-feed `ad_text`; `linkUrl` becomes `landing_page_url`; `videoUrl` triggers a fresh upload.\n- `description`, `videoId` and `existingCreativeId` are Meta-only and return 400.\n\n**LinkedIn**: requires new media (image via `imageUrl` or video via `videoUrl`); a text-only update returns 400.\n\n- Uploads the media, creates a new inline media creative on the same campaign, and removes the old creative. `platformAdId` and `creative.creativeId` move to the new one.\n- The new creative keeps the old one's state. A `DRAFT` or `PAUSED` creative is re-created `DRAFT`, because LinkedIn refuses `PAUSED` before review is `APPROVED`.\n- If the old creative cannot be removed, the new one is deleted and the LinkedIn error is returned.\n- `videoId` and `existingCreativeId` are Meta-only and return 400.\n","properties":{"promotion":{"$ref":"#/components/schemas/MetaPromotion","description":"Not supported. Send null or omit the field, and set the Promotion on the ad in Ads Manager. Any object is rejected with 400 invalid_field_value.\n\nMeta validates creative_sourcing_spec.promotion_metadata_spec on the create call and then discards it, so a Promotion set through the Marketing API never reaches the creative. Verified on 2026-09-11 across Graph v19.0 to v25.0 and every write path.\n"},"creativeFeatures":{"$ref":"#/components/schemas/MetaCreativeFeatures"},"catalogFormat":{"type":"string","enum":["single_image","carousel_images_multi_items","carousel_images_single_item","carousel_slideshows"],"description":"Meta catalog template ads only. Rebuilds the creative with this `template_data.format_option` (same mapping as on create) and repoints the ad at the new creative.\n\nReturns 400 on any other network, on a Meta ad without a catalog template creative, or with `existingCreativeId`. Copy or media fields return 422 on a catalog creative."},"headline":{"type":"string","description":"Meta and LinkedIn (TikTok has no headline slot)"},"longHeadline":{"type":"string","minLength":1,"maxLength":90,"description":"Google Display only. Replaces the responsive display ad's long headline."},"businessName":{"type":"string","minLength":1,"maxLength":25,"description":"Google Display only. Replaces the responsive display ad's business name."},"squareImageUrl":{"type":"string","format":"uri","description":"Google Display only. Uploaded as a new square (1:1) marketing image asset that replaces the current one."},"body":{"type":"string","description":"Primary text. On a Meta asset_feed creative it replaces the feed's only body option (422 when it has several: send `bodies`)."},"bodies":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","minLength":1},"description":"Meta only. The primary text options of an asset_feed creative, one text per option in the order GET /v1/ads/{adId} returns them. Each replaces the option in its position and keeps its rule. A different count returns 422, as does a single-text creative (send `body`). Not with `body`."},"headlines":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","minLength":1},"description":"Meta only. Same as `bodies`, for the headline options (Meta `asset_feed_spec.titles`). Cannot be sent with `headline`. Not the top-level Google `headlines`."},"description":{"type":"string","maxLength":255,"description":"Link description slot (Meta `link_data.description` / `video_data.link_description`, LinkedIn creative description)."},"descriptions":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","minLength":1},"description":"Meta only. Same as `bodies`, for the description options. Cannot be sent with `description`. Not the top-level Google `descriptions`."},"callToAction":{"type":"string"},"linkUrl":{"type":"string","format":"uri"},"imageUrl":{"type":"string","format":"uri"},"videoUrl":{"type":"string","format":"uri"},"videoId":{"type":"string","description":"Meta only. Reuse an already-uploaded ad video (from POST /v1/ads/videos or GET /v1/ads/videos) instead of re-uploading via videoUrl."},"existingCreativeId":{"type":"string","description":"Meta only. Repoint the ad at an existing library creative (from GET /v1/ads/creatives); all other creative fields are ignored."}}},"name":{"type":"string","maxLength":255,"description":"Rename the ad. Now propagated to Meta (POST /{ad-id}); non-Meta platforms return 501."}}}}}},"responses":{"200":{"description":"Ad updated","content":{"application/json":{"schema":{"type":"object","properties":{"ad":{"$ref":"#/components/schemas/Ad"},"message":{"type":"string"}}}}}},"400":{"x-summary":"The update is invalid: send a valid status change and budget, platform-required creative or targeting fields, and at least one updatable field.","description":"Invalid update. Causes:\n\n- Invalid status transition, or budget below minimum.\n- A LinkedIn creative update without imageUrl or videoUrl, or a LinkedIn targeting update without countries or regions.\n- A Google targeting update that is unsupported, empty, mixes locations with the top-level geo fields, or names an unknown country or language code.\n- Code `missing_required_field`: the body has none of the updatable fields (status, budget, targeting, name, creative, headlines, descriptions, finalUrls, assetGroup, demandGen), e.g. `{}` or only misspelled keys. Unknown keys are ignored, so such a body would otherwise change nothing.\n"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The free live ads limit is reached without a card, or the account is not selected: add a card or select it.","description":"Returned with one of these codes:\n\n- `ads_allowance_exceeded`: the team has no payment method on file and has reached the 500 free live ads. Add a card to resume.\n- `ad_account_not_selected`: the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"description":"Ad not found (`ad_not_found`), or `account_not_found` when the ad's connection is on a profile this API key can't access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"x-summary":"The ad cannot take this edit as sent: fix the field named in `param`, or finish the ad's setup on the platform.","description":"The edit cannot be applied. One of:\n\n- A Meta creative edit that cannot be applied in place: a partial edit of a SHARE / page-post / dark post creative, an image, video or call-to-action change that an asset_feed creative holds in its feed, or a text count that does not match the asset feed (`param` names the field).\n- The ad has no campaign or ad group on the platform yet.\n- The Google targeting edit asks for something that is create-only (`locations.customLocations`).\n- A creative field the ad's channel cannot carry: assetGroup on a non-Performance-Max ad, a Google Display field on a Search ad, a pinnedField on a Display headline, or any Google-only field on another platform.\n- A Google creative edit cannot reach Google at all (the ad has no `platformAdId`, or its ad account cannot be loaded). This returns 422 rather than a 200 that changed nothing."},"429":{"x-summary":"Meta allows one write per 30 seconds to this object, or the Meta ad account write guard refused a creative rebuild: wait `Retry-After` (or 30 seconds) and retry.","description":"Two causes, both code `rate_limited`:\n\n- Meta admits one write per 30 seconds to a metered object, ad creatives above all. Zernio waits out two of those windows and replays the call before surfacing this, so it only appears when the object is being edited faster than that. Retry in 30 seconds.\n- A Meta `creative` replace creates a new creative, so it takes the Meta ad account write guard (see `MetaAdAccountWriteLimited`): `details.reason` is `ad_account_busy` (another write held the ad account past a 60-second wait) or `ad_account_write_cap` (30 creates in 5 minutes), with `details.adAccountId`. Wait `Retry-After` seconds.\n"},"501":{"description":"targeting or creative not supported on the platform (supported on Meta, TikTok, and LinkedIn)"},"502":{"x-summary":"Meta failed to produce the media, or the current targeting could not be read and nothing was written: retry the request.","description":"Meta accepted the request then failed to produce the media (upload session, chunk transfer, processing timeout, or a response with no image hash). Inspect `platformError.reason`. Also returned with code `platform_api_error` when a Meta or LinkedIn targeting update cannot read the current targeting: nothing is written, so retry the request."}}},"delete":{"x-resource-group":"ads","operationId":"deleteAd","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit","microsoft"],"summary":"Cancel an ad","description":"Deletes an ad on the platform while keeping its history, and removes empty parents only when they were created through this API.\n\nThe ad is deleted on the platform and marked as cancelled in the database. It is preserved for history.\n\n- OpenAI Ads has no delete API: the ad is archived instead (a terminal state, the closest equivalent).\n- Reddit Ads has no delete either: the ad is archived (`configured_status` ARCHIVED).\n\nTo delete a whole campaign on purpose use `DELETE /v1/ads/campaigns/{campaignId}`.\n\n### Parents\n\nOnly the ad is deleted; a campaign or ad set is never deleted while it still holds another ad. Parents created outside Zernio, and the parents of an ad imported from the platform, are always kept.\n\n### Meta\n\nWhen the ad set and campaign were created by Zernio (by `POST /v1/ads/create` or `POST /v1/ads/boost`) and Meta lists no other ad in the ad set (archived ads count), the emptied ad set is deleted too. The campaign follows once it holds no other ad set.\n\n### LinkedIn\n\nThe ad is a creative inside a campaign inside a campaign group.\n\n- The creative is always removed.\n- The campaign is removed only when Zernio created it and LinkedIn lists no other creative in it that is not archived, canceled or deleted.\n- The campaign group is removed only when Zernio created it and LinkedIn lists no other campaign in it that is not canceled or deleted (archived campaigns count).\n\nIf the creative itself cannot be removed the request fails and no parent is touched.\n\n### X\n\nThe ad is a promoted post inside a line item inside a campaign.\n\n- The promoted post is always removed.\n- The line item is removed only when Zernio created it (by `POST /v1/ads/create` or `POST /v1/ads/boost`) and X lists no other undeleted promoted post in it.\n- The campaign is removed only when Zernio created it and X lists no other undeleted line item in it.\n\nIf X refuses the promoted post delete the request fails and no parent is touched.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ad cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"description":"Ad not found (`ad_not_found`), or `account_not_found` when the ad's connection is on a profile this API key can't access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/ads/{adId}/status":{"put":{"x-resource-group":"ads","operationId":"updateAdStatus","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit","microsoft"],"summary":"Pause or resume a single ad","description":"Pauses or resumes a single ad without touching its ad set, campaign or sibling ads.\n\n### What it flips\n\nAd-scoped pause/resume flips ONLY this ad's own switch, never its parent ad set or campaign, so sibling ads keep running:\n\n- Meta `configured_status`\n- TikTok `operation_status`\n- Google ad group ad status\n- LinkedIn creative\n- Pinterest ad\n- Reddit ad `configured_status`\n\nX is the exception: its smallest switch is the line item.\n\nIt is a thin wrapper over the `status` field of PUT /v1/ads/{adId}, for callers that want a URL symmetric to /v1/ads/campaigns/{campaignId}/status and /v1/ads/ad-sets/{adSetId}/status.\n\n### Own switch vs delivery status\n\nThe ad's own switch is independent of its delivery status.\n\n- An ad paused only because its campaign or ad set is off (`status: paused`, `configuredStatus: ACTIVE`) can still be switched off here.\n- Switching an ad on under a paused campaign leaves it `paused` until the campaign is resumed.\n\nAfter the write the switch is read back from the platform and returned as `configuredStatus`, together with the resulting delivery `status`.\n\n### Identifiers\n\n`{adId}` accepts the same identifier dialects as GET/PUT /v1/ads/{adId}: Zernio hex `_id`, Meta numeric `platformAdId`, or the creative's effective story/media IDs.\n\n`platform` is inferred from the ad, so it's not required in the body.\n\n### Skips\n\nThese requests are skipped:\n\n- Ads in terminal statuses (rejected, completed, cancelled).\n- A request whose target already matches the ad's own switch as read LIVE from the platform. A stored value is never trusted alone, since the switch may have been changed in the platform's own UI.\n\nA skip also returns that live read. The rolled-up `status` never decides a skip.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adId","in":"path","required":true,"schema":{"type":"string"},"description":"Zernio `_id` (hex), Meta `platformAdId` (numeric), or one of the creative's effective story/media IDs."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["active","paused"]}}}}}},"responses":{"200":{"description":"Ad status updated (or skipped when no change was needed)","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"integer","description":"1 when the switch was written, 0 when skipped"},"skipped":{"type":"integer","description":"1 when skipped (terminal status, or the ad's own switch already in the target state), else 0"},"status":{"type":"string","description":"The ad's delivery status after the call, as the platform reports it when it can be read back (e.g. `paused` for an ad switched on under a paused campaign)"},"configuredStatus":{"type":["string","null"],"description":"The ad's own on/off switch (`ACTIVE` / `PAUSED`), re-read from the platform after the write. Null where the platform exposes no per-ad switch (X) or the read-back failed and the platform does not store one."},"message":{"type":"string","description":"Human-readable summary (present only when skipped), e.g. \"No change: the ad's own switch is already off\""}}}}}},"400":{"description":"Invalid input"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The free live ads limit is reached without a card, or the account is not selected: add a card or select it.","description":"Forbidden. The code says why:\n\n- `ads_allowance_exceeded`: the team has no payment method on file and has reached the 500 free live ads. Add a card to resume.\n- `ad_account_not_selected`: the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"description":"Ad not found (`ad_not_found`), or `account_not_found` when the ad's connection is on a profile this API key can't access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/ads/campaigns/{campaignId}/assets":{"get":{"x-resource-group":"ads","operationId":"listCampaignAssets","summary":"List campaign assets","tags":["Ad Campaigns"],"x-platforms":["google"],"description":"Lists the sitelinks, callouts and other assets attached directly to a Google campaign.\n\nFresh reads are cached for 10 minutes; exhausted quota may return the last successful read with stale=true. Inherited assets are not included.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Numeric Google platform id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio Google Ads connection id."}},{"name":"adAccountId","in":"query","schema":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."}},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string","pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"}}],"responses":{"200":{"description":"Assets returned.","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"sitelinks":{"type":"array","items":{"type":"object","properties":{"assetResourceName":{"type":"string"},"campaignAssetResourceName":{"type":"string"},"text":{"type":"string"},"linkUrl":{"type":"string","format":"uri"},"description1":{"type":"string"},"description2":{"type":"string"}}}},"callouts":{"type":"array","items":{"type":"object","properties":{"assetResourceName":{"type":"string"},"campaignAssetResourceName":{"type":"string"},"calloutText":{"type":"string"}}}},"structuredSnippets":{"type":"array","items":{"type":"object","properties":{"assetResourceName":{"type":"string"},"campaignAssetResourceName":{"type":"string"},"header":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}}}},"images":{"type":"array","items":{"type":"object","properties":{"assetResourceName":{"type":"string"},"campaignAssetResourceName":{"type":"string"},"imageUrl":{"type":"string","format":"uri","description":"Google-hosted copy of the image."},"width":{"type":"integer"},"height":{"type":"integer"}}}},"cachedAt":{"type":["string","null"],"format":"date-time","description":"Time of the cached Google read. Null when no cache was used."},"stale":{"type":"boolean","description":"True when exhausted quota required returning the last successful read."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Forbidden. One of:\n\n- Ads access is required.\n- Code `ad_account_not_selected`: the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Only supported on Google Ads."}}},"post":{"x-resource-group":"ads","operationId":"attachCampaignAssets","summary":"Attach campaign assets","tags":["Ad Campaigns"],"x-platforms":["google"],"description":"Adds sitelinks, callouts, structured snippets and images to a Google campaign in one step.\n\nCreates and attaches sitelinks, callouts, structured snippets and image assets in one Google mutation. Google shows images only on accounts it deems eligible (account age, policy history, vertical).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Numeric Google platform id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio Google Ads connection id."},"adAccountId":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."},"customerId":{"type":"string","deprecated":true,"pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"},"sitelinks":{"type":"array","items":{"$ref":"#/components/schemas/GoogleSitelink"},"minItems":2,"maxItems":20},"callouts":{"type":"array","items":{"type":"string","minLength":1,"maxLength":25},"minItems":1,"maxItems":20},"structuredSnippets":{"type":"array","items":{"$ref":"#/components/schemas/GoogleStructuredSnippet"},"minItems":1,"maxItems":20},"images":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1,"maxItems":20,"description":"Public image URLs, uploaded to Google as image assets. Landscape 1.91:1 (min 600x314) or square 1:1 (min 300x300), up to 5 MB each."}},"description":"Provide at least one of sitelinks, callouts, structuredSnippets or images. Sitelink description1 and description2 must be supplied together."},"example":{"accountId":"64b1f0c8a1b2c3d4e5f60718","adAccountId":"1234567890","sitelinks":[{"text":"Pricing","linkUrl":"https://zernio.com/pricing"},{"text":"Documentation","linkUrl":"https://zernio.com/docs"}],"callouts":["Fast setup"],"structuredSnippets":[{"header":"Types","values":["Scheduling","Analytics","Messaging"]}]}}}},"responses":{"201":{"description":"Assets created and attached.","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"sitelinkAssetResourceNames":{"type":"array","items":{"type":"string"}},"calloutAssetResourceNames":{"type":"array","items":{"type":"string"}},"structuredSnippetAssetResourceNames":{"type":"array","items":{"type":"string"}},"imageAssetResourceNames":{"type":"array","items":{"type":"string"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Ads access is required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix it, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Only supported on Google Ads."}}},"put":{"x-resource-group":"ads","operationId":"updateCampaignAssets","summary":"Update campaign assets","tags":["Ad Campaigns"],"x-platforms":["google"],"description":"Edits a Google campaign's existing assets, such as sitelinks or callouts, in place; the change applies everywhere that asset is used.\n\nSend updates with assetResourceName and the fields to change. An asset is shared: changes affect every attachment using it. Omitted fields stay unchanged. The operation consumes the Google operations budget and invalidates affected cached lists.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Numeric Google platform id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","updates"],"properties":{"accountId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio Google Ads connection id."},"adAccountId":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."},"customerId":{"type":"string","deprecated":true,"pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"},"updates":{"type":"array","items":{"$ref":"#/components/schemas/GoogleAssetUpdate"},"minItems":1,"maxItems":20}}},"example":{"accountId":"64b1f0c8a1b2c3d4e5f60718","adAccountId":"1234567890","updates":[{"assetResourceName":"customers/1234567890/assets/123","calloutAsset":{"calloutText":"Simple integration"}}]}}}},"responses":{"200":{"description":"Assets returned.","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Ads access is required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Only supported on Google Ads."}}},"delete":{"x-resource-group":"ads","operationId":"removeCampaignAssets","summary":"Remove campaign assets","tags":["Ad Campaigns"],"x-platforms":["google"],"description":"Detaches assets from a Google campaign without deleting them, so they stay in the account and on anything else they are attached to.\n\nGoogle assets cannot be deleted. Other attachments remain. assetResourceNames is retained for compatibility. Fields go in the query string. A JSON body with the same fields is also accepted and, when sent, the query string is ignored.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Numeric Google platform id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"description":"Zernio Google Ads connection id."},{"name":"adAccountId","in":"query","schema":{"type":"string","pattern":"^\\d+$"},"description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Alias of adAccountId, kept for existing callers"},{"name":"assetResourceNames","in":"query","required":true,"style":"form","explode":true,"schema":{"type":"array","minItems":1,"items":{"type":"string"}},"description":"Asset resource names, retained for compatibility. Repeat the parameter or pass a comma-separated list."},{"name":"campaignAssetResourceNames","in":"query","required":true,"style":"form","explode":true,"schema":{"type":"array","minItems":1,"items":{"type":"string"}},"description":"campaign_asset resource names to remove, e.g. customers/1234567890/campaignAssets/456~123~CALLOUT. Repeat the parameter or pass a comma-separated list."}],"responses":{"200":{"description":"Assets returned.","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Ads access is required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection), or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Only supported on Google Ads."}}}},"/v1/ads/ad-sets/{adSetId}/assets":{"get":{"x-resource-group":"ads","operationId":"listAdGroupAssets","summary":"List ad-group assets","tags":["Ad Campaigns"],"x-platforms":["google"],"description":"Lists the sitelinks, callouts, snippets and images attached directly to a Google ad group, not those inherited from the campaign or account.\n\nFresh reads are cached for 10 minutes; exhausted quota may return the last successful read with stale=true. Inherited assets are not included.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adSetId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Numeric Google platform id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio Google Ads connection id."}},{"name":"adAccountId","in":"query","schema":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."}},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string","pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"}}],"responses":{"200":{"description":"Assets returned.","content":{"application/json":{"schema":{"type":"object","properties":{"adGroupId":{"type":"string"},"sitelinks":{"type":"array","items":{"type":"object","properties":{"assetResourceName":{"type":"string"},"adGroupAssetResourceName":{"type":"string"},"text":{"type":"string"},"linkUrl":{"type":"string","format":"uri"},"description1":{"type":"string"},"description2":{"type":"string"}}}},"callouts":{"type":"array","items":{"type":"object","properties":{"assetResourceName":{"type":"string"},"adGroupAssetResourceName":{"type":"string"},"calloutText":{"type":"string"}}}},"structuredSnippets":{"type":"array","items":{"type":"object","properties":{"assetResourceName":{"type":"string"},"adGroupAssetResourceName":{"type":"string"},"header":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}}}},"images":{"type":"array","items":{"type":"object","properties":{"assetResourceName":{"type":"string"},"adGroupAssetResourceName":{"type":"string"},"imageUrl":{"type":"string","format":"uri","description":"Google-hosted copy of the image."},"width":{"type":"integer"},"height":{"type":"integer"}}}},"cachedAt":{"type":["string","null"],"format":"date-time","description":"Time of the cached Google read. Null when no cache was used."},"stale":{"type":"boolean","description":"True when exhausted quota required returning the last successful read."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Ads access is required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix it, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Only supported on Google Ads."}}},"post":{"x-resource-group":"ads","operationId":"attachAdGroupAssets","summary":"Attach ad-group assets","tags":["Ad Campaigns"],"x-platforms":["google"],"description":"Creates sitelinks, callouts, structured snippets or image assets and attaches them to a Google ad group in one step.\n\nCreates and attaches sitelinks, callouts, structured snippets and image assets in one Google mutation. Google shows images only on accounts it deems eligible (account age, policy history, vertical).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adSetId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Numeric Google platform id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio Google Ads connection id."},"adAccountId":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."},"customerId":{"type":"string","deprecated":true,"pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"},"sitelinks":{"type":"array","items":{"$ref":"#/components/schemas/GoogleSitelink"},"minItems":2,"maxItems":20},"callouts":{"type":"array","items":{"type":"string","minLength":1,"maxLength":25},"minItems":1,"maxItems":20},"structuredSnippets":{"type":"array","items":{"$ref":"#/components/schemas/GoogleStructuredSnippet"},"minItems":1,"maxItems":20},"images":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1,"maxItems":20,"description":"Public image URLs, uploaded to Google as image assets. Landscape 1.91:1 (min 600x314) or square 1:1 (min 300x300), up to 5 MB each."}},"description":"Provide at least one of sitelinks, callouts, structuredSnippets or images. Sitelink description1 and description2 must be supplied together."},"example":{"accountId":"64b1f0c8a1b2c3d4e5f60718","customerId":"1234567890","sitelinks":[{"text":"Pricing","linkUrl":"https://zernio.com/pricing"},{"text":"Documentation","linkUrl":"https://zernio.com/docs"}],"callouts":["Fast setup"],"structuredSnippets":[{"header":"Types","values":["Scheduling","Analytics","Messaging"]}]}}}},"responses":{"201":{"description":"Assets created and attached.","content":{"application/json":{"schema":{"type":"object","properties":{"adGroupId":{"type":"string"},"sitelinkAssetResourceNames":{"type":"array","items":{"type":"string"}},"calloutAssetResourceNames":{"type":"array","items":{"type":"string"}},"structuredSnippetAssetResourceNames":{"type":"array","items":{"type":"string"}},"imageAssetResourceNames":{"type":"array","items":{"type":"string"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Ads access is required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Only supported on Google Ads."}}},"put":{"x-resource-group":"ads","operationId":"updateAdGroupAssets","summary":"Update ad-group assets","tags":["Ad Campaigns"],"x-platforms":["google"],"description":"Edits a Google ad group's existing assets in place; the change applies everywhere that asset is used.\n\nSend updates with assetResourceName and the fields to change. An asset is shared: changes affect every attachment using it. Omitted fields stay unchanged. The operation consumes the Google operations budget and invalidates affected cached lists.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adSetId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Numeric Google platform id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","updates"],"properties":{"accountId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio Google Ads connection id."},"adAccountId":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."},"customerId":{"type":"string","deprecated":true,"pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"},"updates":{"type":"array","items":{"$ref":"#/components/schemas/GoogleAssetUpdate"},"minItems":1,"maxItems":20}}},"example":{"accountId":"64b1f0c8a1b2c3d4e5f60718","customerId":"1234567890","updates":[{"assetResourceName":"customers/1234567890/assets/123","calloutAsset":{"calloutText":"Simple integration"}}]}}}},"responses":{"200":{"description":"Assets returned.","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Forbidden. One of:\n\n- Ads access is required.\n- Code `ad_account_not_selected`: the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Only supported on Google Ads."}}},"delete":{"x-resource-group":"ads","operationId":"removeAdGroupAssets","summary":"Remove ad-group assets","tags":["Ad Campaigns"],"x-platforms":["google"],"description":"Detaches assets from a Google ad group without deleting them, so they stay in the account and on anything else they are attached to.\n\nGoogle assets cannot be deleted. Other attachments remain. assetResourceNames is retained for compatibility. Fields go in the query string. A JSON body with the same fields is also accepted and, when sent, the query string is ignored.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adSetId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Numeric Google platform id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"description":"Zernio Google Ads connection id."},{"name":"adAccountId","in":"query","schema":{"type":"string","pattern":"^\\d+$"},"description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Alias of adAccountId, kept for existing callers"},{"name":"assetResourceNames","in":"query","required":true,"style":"form","explode":true,"schema":{"type":"array","minItems":1,"items":{"type":"string"}},"description":"Asset resource names, retained for compatibility. Repeat the parameter or pass a comma-separated list."},{"name":"adGroupAssetResourceNames","in":"query","required":true,"style":"form","explode":true,"schema":{"type":"array","minItems":1,"items":{"type":"string"}},"description":"ad_group_asset resource names to remove, e.g. customers/1234567890/adGroupAssets/456~123~CALLOUT. Repeat the parameter or pass a comma-separated list."}],"responses":{"200":{"description":"Assets returned.","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Ads access is required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix it, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Only supported on Google Ads."}}}},"/v1/ads/campaigns/{campaignId}/analytics":{"get":{"x-resource-group":"ads","operationId":"getCampaignAnalytics","tags":["Ad Insights"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit","microsoft"],"summary":"Get campaign analytics","description":"Returns a campaign's performance summary and daily timeline, with optional breakdowns by age, gender and other audience dimensions.\n\nOne call returns analytics for a whole campaign:\n\n- summary metrics\n- a daily timeline over the requested date range (summed across the campaign's ads)\n- optional demographic breakdowns\n\nBreakdowns are fetched live from Meta, TikTok or LinkedIn at the campaign level (one call per dimension, no per-ad fan-out). So an agency dashboard gets campaign-level age/gender/placement/etc. without summing thousands of per-ad reads.\n\n`campaignId` is the platform campaign id; pass `platform` when a campaign id could be ambiguous across platforms.\n\nIf no date range is provided, it defaults to the last 90 days. The date range is capped at 730 days max.\n\n### History\n\nWhen an ad account connects, Zernio imports its last 90 days of metrics. `summary` and `daily` come from those synced metrics, so they hold no data for days before that.\n\nBreakdowns and Google's impression share are read live from the platform over the requested range, so they are not limited by the import.\n\nWhen the campaign belongs to a Meta ad account, a range reaching further back answers `202` with `backfillPending: true` and the covered part. The older days (up to 730 days back) are imported in the background; repeat the request until it returns 200. Other platforms never return `202`.\n\n### Google impression share\n\nGoogle adds these under analytics.summary for the requested inclusive range:\n\n- searchImpressionShare\n- searchBudgetLostImpressionShare\n- searchRankLostImpressionShare\n- searchTopImpressionShare\n- searchAbsoluteTopImpressionShare\n\nThese ratios are queried together without daily segmentation and cached for 10 minutes. Unavailable values are null. analytics.impressionShareCache reports cachedAt and stale independently of synced metrics.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform campaign id (platformCampaignId)."},{"name":"platform","in":"query","schema":{"type":"string"},"description":"Disambiguate when the campaign id exists across platforms (e.g. facebook, instagram)."},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Start of date range (YYYY-MM-DD). Defaults to 90 days ago."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"End of date range (YYYY-MM-DD). Defaults to today. Max 730-day range."},{"name":"breakdowns","in":"query","schema":{"type":"string"},"description":"Comma-separated breakdown dimensions.\n\n- **Meta**: age, gender, country, publisher_platform, device_platform, region, platform_position, impression_device, video_asset, image_asset, body_asset, title_asset.\n- **TikTok**: gender, age, country (or country_code), publisher_platform (or platform), ac, language, placement. TikTok serves at most 365 days per breakdown, so a longer range is read over its last 365 days and `analytics.breakdownsRange` says which window.\n- **LinkedIn** (firmographics): job_title, job_function, seniority, industry, company, company_size, country, region. Rows carry the raw pivot `value` plus a resolved `name`. Aggregated over the whole range, delayed 12-24h, omitting segments with fewer than 3 events.\n\n**Errors and gaps:**\n\n- A known dimension the platform cannot break down by is listed in `analytics.unsupportedBreakdowns` instead of dropped (with guidance in `analytics.breakdownHints` where an alternative exists); the rest of the response is unchanged.\n- An unknown name returns 400.\n- A TikTok dimension that fails is listed in `analytics.breakdownErrors` and the response stays 200.\n- Metrics TikTok refuses for a dimension are listed in `analytics.breakdownDroppedMetrics`, and row values derived from them are null.\n"}],"responses":{"200":{"description":"Campaign analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignAnalyticsResponse"},"example":{"campaign":{"id":"123456789","platform":"google"},"analytics":{"summary":{"searchImpressionShare":0.42,"searchBudgetLostImpressionShare":0.13,"searchRankLostImpressionShare":0.45,"searchTopImpressionShare":0.31,"searchAbsoluteTopImpressionShare":null},"impressionShareCache":{"cachedAt":"2026-09-09T10:00:00Z","stale":false},"daily":[]}}}}},"202":{"x-summary":"Historical data is incomplete because the Meta backfill is still pending: retry later for the full history.","description":"Meta only. Historical data is incomplete and backfill remains pending.","headers":{"Retry-After":{"$ref":"#/components/headers/BackfillRetryAfter"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CampaignAnalyticsResponse"},{"type":"object","required":["backfillPending"],"properties":{"backfillPending":{"type":"boolean","description":"Always true on this response. Part of the requested range is still being backfilled; retry until the request returns 200."}}}]}}}},"400":{"x-summary":"A query parameter is invalid, such as an unknown breakdown dimension: the message lists the supported values.","description":"Invalid parameter (e.g. an unknown `breakdowns` dimension). The message lists the offending value(s) and the supported set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Forbidden. One of:\n\n- Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.\n- Code `ad_account_not_selected`: the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"The team's analytics read cap was reached (`details.scope` is `campaign-analytics`), or the Google operations budget or quota is exhausted without a cached impression-share result."}}}},"/v1/ads/preview":{"post":{"x-resource-group":"ads","operationId":"generateAdPreviews","tags":["Ad Creatives"],"x-platforms":["meta"],"summary":"Render pre-create ad previews","description":"Shows how a Meta creative will look in each placement before you create the ad, as embeddable previews.\n\nRenders how a creative would look per placement BEFORE any ad exists, via Meta's\n`/generatepreviews`. Provide exactly one creative source: `existingCreativeId` or `creativeSpec`.\nEach preview is an HTML `<iframe>` snippet embeddable directly. Unknown `formats` values\nreturn Meta's 400 verbatim.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","adAccountId"],"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id used to resolve the Meta token."},"adAccountId":{"type":"string","description":"Platform ad account id (Meta act_<n>, Google customer id, LinkedIn account id, ...)."},"formats":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string"},"description":"Meta ad_format values, one preview per format. Defaults to [DESKTOP_FEED_STANDARD]."},"existingCreativeId":{"type":"string","description":"Preview an existing ad-account creative by id. Mutually exclusive with creativeSpec."},"creativeSpec":{"type":"object","additionalProperties":true,"description":"Raw Meta creative spec forwarded to /generatepreviews. Mutually exclusive with existingCreativeId. An `object_story_spec` without `page_id` or `instagram_user_id`, and a `source_instagram_media_id` spec without `instagram_user_id`, get the connection's Facebook Page and Instagram account, as a create would."}}}}}},"responses":{"200":{"description":"Rendered previews","content":{"application/json":{"schema":{"type":"object","properties":{"previews":{"type":"array","items":{"type":"object","properties":{"format":{"type":"string"},"html":{"type":["string","null"],"description":"Meta's <iframe> snippet; null when Meta returned no preview for the format."}}}}}}}}},"400":{"description":"Invalid input, or Meta rejected the creative spec / ad_format; the message carries Meta's error"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/MetaRateLimited"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/{adId}/preview":{"get":{"x-resource-group":"ads","operationId":"getAdPreviews","tags":["Ad Creatives"],"x-platforms":["meta"],"summary":"Render previews of an existing ad","description":"Shows how an existing Meta ad looks in each placement, as embeddable previews.\n\nRenders an EXISTING ad per placement via Meta's `/{ad_id}/previews`. Each preview is an HTML\n`<iframe>` snippet embeddable directly. Unknown `formats` values return Meta's 400 verbatim.\n\n**Meta ads that are not synced yet.** Pass `accountId` with a Meta platform ad id that is not in\nZernio's store to render it live through that connection; the response carries `synced: false`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adId","in":"path","required":true,"schema":{"type":"string"},"description":"Zernio ad id (24-char hex) or Meta platform ad id."},{"$ref":"#/components/parameters/UnsyncedMetaAdAccountId"},{"name":"formats","in":"query","schema":{"type":"string"},"description":"Comma-separated Meta ad_format values (max 10), one preview per format. Defaults to DESKTOP_FEED_STANDARD."}],"responses":{"200":{"description":"Rendered previews","content":{"application/json":{"schema":{"type":"object","properties":{"adId":{"type":"string"},"synced":{"type":"boolean","description":"False when the ad was read live from Meta because it is not in Zernio's store (request made with `accountId`)."},"previews":{"type":"array","items":{"type":"object","properties":{"format":{"type":"string"},"html":{"type":["string","null"],"description":"Meta's <iframe> snippet; null when Meta returned no preview for the format."}}}}}}}}},"400":{"description":"Invalid input, or Meta rejected the ad_format; the message carries Meta's error"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"description":"Ad not found"},"409":{"x-summary":"Several active connections reach this ad account, so the target is ambiguous: keep only one connected for this key.","description":"Several active connections on the API key's profiles reach the ad account of this ad (code `ambiguous_account`), so the connection to act with is ambiguous. Keep one of them connected or move the others to a profile this key cannot access."},"429":{"$ref":"#/components/responses/MetaRateLimited"},"501":{"x-summary":"Only Meta ads support this operation, and a non-Meta `accountId` also fails: use a Meta ad and connection.","description":"Only supported on Meta (facebook/instagram). `accountId` naming a connection that is not Meta also answers 501."}}}},"/v1/ads/{adId}/review":{"get":{"x-resource-group":"ads","operationId":"getAdReview","tags":["Ad Campaigns"],"x-platforms":["tiktok","google","meta"],"summary":"Read the platform's review verdict for an ad","description":"Shows whether the platform approved an ad, where it may not deliver, and every rejection reason, without re-enabling a paused ad.\n\nIt reads the ad's review verdict from the platform now, including every rejection reason with TikTok's suggestion and the piece of content it refers to. It is read-only, so it works on a paused ad without re-enabling it.\n\nSupported on TikTok, Google and Meta. Other platforms return 501.\n\n### Google\n\nReads `ad_group_ad.policy_summary` live. `approvalStatus` and `reviewStatus` are Google's verbatim:\n\n- `approvalStatus`: APPROVED, APPROVED_LIMITED, AREA_OF_INTEREST_ONLY, DISAPPROVED, UNKNOWN.\n- `reviewStatus`: REVIEW_IN_PROGRESS, REVIEWED, UNDER_APPEAL, ELIGIBLE_MAY_SERVE.\n- `approved`: true for the three approved statuses, false for DISAPPROVED, null otherwise.\n\n`policyTopics` carries every policy topic entry with its `type` (PROHIBITED, LIMITED, ...) and Google's `evidences` and `constraints` verbatim. Each PROHIBITED topic is also listed in `rejections` (reason = the topic).\n\nThe `forbidden*` arrays are TikTok-only and always empty on Google.\n\n### Meta (Facebook and Instagram ads)\n\nReads the Ad's `ad_review_feedback`, `effective_status` and `issues_info` live.\n\n- `reviewStatus`: Meta's `effective_status` verbatim (ACTIVE, PAUSED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, WITH_ISSUES, IN_PROCESS, ...).\n- `approved`: true for ACTIVE and PREAPPROVED, false for DISAPPROVED, null otherwise.\n- `reviewFeedback`: Meta's feedback verbatim, as `global` (reason -> explanation) and `placementSpecific` (placement -> reason -> explanation).\n- `issues`: Meta's `issues_info` verbatim.\n\nEach global reason is listed in `rejections`, and so is each placement-specific reason, with that placement in its `forbiddenPlacements`. The review's `forbiddenPlacements` lists every placement with feedback.\n\n`forbiddenAges`, `forbiddenLocations` and `forbiddenOperatingSystems` are always empty on Meta.\n\nWhen Meta returns no feedback (usually an ad in review or approved everywhere), the status comes back with empty `rejections` and empty `reviewFeedback` maps. An ACTIVE ad rejected on one placement still carries that placement's feedback.\n\nThe `effective_status` read is also stored on the ad, so `GET /v1/ads/{adId}` returns it next. A deleted ad answers 404.\n\n### Meta ads that are not synced yet\n\nPass `accountId` with a Meta platform ad id that is not in Zernio's store to read its review live through that connection. The response then has `adId: null`, `synced: false`, and nothing is stored. Synced ads answer `synced: true`.\n\n### TikTok\n\nTikTok uses `/ad/review_info/`. Use it alongside the ad's `platformStatus`:\n\n- `AD_STATUS_AUDIT`: the ad is in review (maps to `status: pending_review`).\n- `AD_STATUS_AD_PRE_ONLINE`: it passed and is about to deliver (also maps to `status: pending_review`).\n- `AD_STATUS_AUDIT_DENY`: maps to `rejected`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adId","in":"path","required":true,"schema":{"type":"string"},"description":"Zernio ad id (24-char hex) or the platform ad id."},{"$ref":"#/components/parameters/UnsyncedMetaAdAccountId"}],"responses":{"200":{"description":"The review verdict","content":{"application/json":{"schema":{"type":"object","properties":{"adId":{"type":["string","null"],"description":"Zernio ad id; null for an unsynced Meta ad read with `accountId`."},"platform":{"type":"string"},"platformAdId":{"type":"string"},"synced":{"type":"boolean","description":"False when the ad was read live from Meta because it is not in Zernio's store."},"review":{"type":"object","properties":{"approved":{"type":["boolean","null"],"description":"TikTok `is_approved`. Google and Meta: derived from the platform status (see the description)."},"reviewStatus":{"type":["string","null"],"description":"TikTok `review_status`, verbatim: ALL_AVAILABLE (approved everywhere), PART_AVAILABLE (approved for part of the targeting), UNAVAILABLE (rejected). Google: `review_status`. Meta: the ad's `effective_status`."},"forbiddenPlacements":{"type":"array","items":{"type":"string"}},"forbiddenAges":{"type":"array","items":{"type":"string"}},"forbiddenLocations":{"type":"array","items":{"type":"string"}},"forbiddenOperatingSystems":{"type":"array","items":{"type":"string"}},"rejections":{"type":"array","description":"One entry per rejected piece of content (TikTok `reject_info`). Empty when the ad was approved.","items":{"type":"object","properties":{"reasons":{"type":"array","items":{"type":"string"}},"suggestion":{"type":["string","null"],"description":"TikTok's advice for fixing the rejection."},"forbiddenPlacements":{"type":"array","items":{"type":"string"}},"forbiddenAges":{"type":"array","items":{"type":"string"}},"forbiddenLocations":{"type":"array","items":{"type":"string"}},"content":{"type":["object","null"],"description":"The content TikTok reviewed.","properties":{"type":{"type":["string","null"],"description":"MODE_STRING, MODE_IMAGE, MODE_VIDEO or MODE_CAROUSEL_MUSIC."},"text":{"type":["string","null"]},"imageId":{"type":["string","null"]},"videoId":{"type":["string","null"]},"musicId":{"type":["string","null"]}}}}}},"approvalStatus":{"type":["string","null"],"description":"Google only. ad_group_ad.policy_summary.approval_status, verbatim."},"policyTopics":{"type":"array","description":"Google only. ad_group_ad.policy_summary.policy_topic_entries.","items":{"type":"object","properties":{"topic":{"type":["string","null"]},"type":{"type":["string","null"],"description":"PROHIBITED, LIMITED, FULLY_LIMITED, DESCRIPTIVE, BROADENING, AREA_OF_INTEREST_ONLY."},"evidences":{"type":"array","items":{"type":"object"},"description":"Google's PolicyTopicEvidence objects, verbatim."},"constraints":{"type":"array","items":{"type":"object"},"description":"Google's PolicyTopicConstraint objects, verbatim."}}}},"reviewFeedback":{"type":"object","description":"Meta only. The Ad's `ad_review_feedback`, verbatim. Both maps are empty when Meta returned no feedback (approved or in-review ad).","properties":{"global":{"type":"object","additionalProperties":{"type":"string"},"description":"Meta `global`: policy or reason -> Meta's explanation."},"placementSpecific":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"string"}},"description":"Meta `placement_specific`: placement (facebook, instagram, ...) -> reason -> Meta's explanation."}}},"issues":{"type":"array","items":{"type":"object"},"description":"Meta only. The Ad's `issues_info` objects (`error_code`, `error_message`, `error_summary`, `error_type`, `level`), verbatim."},"readAt":{"type":"string","format":"date-time","description":"When the verdict was read from the platform."}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"description":"Ad not found, it has no platform ad id yet, or the platform has no review record for it"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"x-summary":"Only TikTok, Google and Meta ads support ad review: use an ad and connection on one of those platforms.","description":"Only supported on TikTok, Google and Meta (Facebook and Instagram ads). `accountId` naming a connection that is not Meta also answers 501."}}}},"/v1/ads/{adId}/tiktok-smart-plus-review":{"get":{"x-resource-group":"ads","operationId":"getTikTokSmartPlusAdReview","tags":["Ad Campaigns"],"x-platforms":["tiktok"],"summary":"Review status of each creative in a TikTok Smart+ ad","description":"Shows which Spark post, video or carousel of an Upgraded Smart+ ad TikTok approved or rejected, with every rejection reason, keyed by the TikTok post id for a Spark post.\n\nIt reads TikTok's `/smart_plus/ad/review_info/` live (read-only, works on a paused ad) for the Smart+ ad that holds `adId`. It returns the ad-level verdict plus one entry per creative.\n\n### Which ad is read\n\n`adId` may be the Smart+ ad itself or any creative of it synced as its own ad. Zernio finds the Smart+ ad in the ad's ad group through `/smart_plus/ad/get/`, and uses the ad group's only Smart+ ad when no creative list names the ad.\n\n### Creative fields\n\n`materialType`, `tiktokItemId`, `videoId`, `name` and `operationStatus` come from the Smart+ ad's `creative_list`. Some entries come back with the review verdict and null descriptive fields:\n\n- creatives TikTok added on its own, which it leaves out of that list (creator content, authorized TikTok posts, Creative Library content)\n- each image of a carousel, which TikTok lists under its own material id\n\nTikTok returns no review timestamp; `readAt` is when Zernio read it.\n\n### Quota and caching\n\nTikTok's review endpoint has a strict quota of its own (TikTok documents neither the quota nor its scope). One TikTok call reads the review of the live Smart+ ads of the ad group, up to 50 creatives in total (TikTok refuses more).\n\nEach review is stored per connection, advertiser and Smart+ ad. A review read in the last 10 minutes is served from the store, so sibling ads are answered without a TikTok call and `readAt` can be up to 10 minutes old. An older one is read again.\n\nRead reviews when you need them instead of sweeping every ad on a loop.\n\n### Over quota\n\nWhen TikTok answers over quota, Zernio returns 429. It then answers 429 for that advertiser and connection without calling TikTok:\n\n- for about 60 seconds at first\n- then 120, and up to 240, while TikTok keeps refusing\n- about 60 again after a successful call\n\nEach pause has up to 10% of random jitter, with the time left as `Retry-After`. Reviews read in the last 10 minutes are still served.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adId","in":"path","required":true,"schema":{"type":"string"},"description":"Zernio ad id (24-char hex) or the TikTok ad id: the Smart+ ad id or the ad id of one of its creatives."}],"responses":{"200":{"description":"The Smart+ ad's review verdict per creative","content":{"application/json":{"schema":{"type":"object","properties":{"adId":{"type":"string"},"platform":{"type":"string","enum":["tiktok"]},"platformAdId":{"type":"string"},"smartPlusAdId":{"type":"string","description":"The TikTok Smart+ ad whose review this is."},"review":{"$ref":"#/components/schemas/TikTokSmartPlusAdLevelReview"},"materials":{"type":"array","description":"One entry per creative TikTok reviewed (`material_review_infos`).","items":{"$ref":"#/components/schemas/TikTokSmartPlusMaterialReview"}},"readAt":{"type":"string","format":"date-time","description":"When the verdict was read from TikTok."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"x-summary":"The ad is not found, has no TikTok IDs yet, or is not in a Smart+ ad group: check the ad.","description":"Ad not found, it has no TikTok ad or ad group id yet, or no Smart+ ad of its ad group holds it. In the last case `details.listedSmartPlusAds` is how many Smart+ ads TikTok lists in the ad group, deleted ones included: 0 means the ad group lists none."},"422":{"description":"The TikTok ad is not an Upgraded Smart+ ad (read it with GET /v1/ads/{adId}/review)"},"429":{"description":"Rate limited. TikTok's general limit answers `Retry-After: 10`; its stricter Smart+ review quota (which behaves per advertiser) answers `Retry-After` of up to 1056 seconds, the time left before Zernio calls TikTok's review endpoint again for this advertiser and connection.","$ref":"#/components/responses/RateLimited"},"501":{"description":"Only supported on TikTok"}}}},"/v1/ads/{adId}/media":{"get":{"x-resource-group":"ads","operationId":"getAdMedia","tags":["Ad Creatives"],"x-platforms":["meta"],"summary":"Direct video and image URLs for an ad","description":"Returns fresh, short-lived download links for every image and video a Meta ad uses, including the original media of a boosted Instagram post.\n\nThe direct signed URLs cover every video and image asset used by the ad's live creative, normalised across shapes:\n\n- single image/video\n- carousel\n- Reels/Story (`object_story_spec.video_data`)\n- dynamic creative (`asset_feed_spec`)\n\nVideo items include Meta's poster thumbnail and the video's Meta id when available.\n\n### Boosted Instagram posts\n\nCreatives with no image of their own return the original post's media: the image, the video with its cover as `thumbnailUrl`, or every child of a carousel post with `index`.\n\nWhen the connection cannot read the Instagram post, the item is a 1080px rendering of the creative instead.\n\n### URL lifetime\n\nThis endpoint reads Meta live rather than the stored creative blob, because Meta's signed fbcdn URLs carry an `oe=<hex>` expiration (image_url ~24 h, video source ~12 d).\n\nTreat URLs as short-lived: re-fetch this endpoint before serving or downloading assets instead of caching URLs beyond that window.\n\n**Meta ads that are not synced yet.** Pass `accountId` with a Meta platform ad id that is not in Zernio's store to read its media live through that connection; the response carries `synced: false`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adId","in":"path","required":true,"schema":{"type":"string"},"description":"Zernio ad id (24-char hex) or platform ad id."},{"$ref":"#/components/parameters/UnsyncedMetaAdAccountId"}],"responses":{"200":{"description":"Media assets","content":{"application/json":{"schema":{"type":"object","properties":{"adId":{"type":"string"},"platform":{"type":"string","description":"'facebook' or 'instagram'. Only Meta is supported for now."},"synced":{"type":"boolean","description":"False when the ad was read live from Meta because it is not in Zernio's store (request made with `accountId`)."},"media":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["image","video"]},"url":{"type":"string","description":"Direct file URL (signed; short-lived, see description)."},"thumbnailUrl":{"type":"string","description":"Video poster URL (videos only)."},"videoId":{"type":"string","description":"Meta video id (videos only), reusable as video.id on the create endpoints."},"length":{"type":"number","description":"Video length in seconds (videos only)."},"index":{"type":"integer","description":"0-based position for carousel children or asset_feed_spec entries."}}}}}}}}},"400":{"description":"Invalid input"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"description":"Ad not found"},"409":{"x-summary":"Several active connections reach this ad account, so the target is ambiguous: keep only one connected for this key.","description":"Several active connections on the API key's profiles reach the ad account of this ad (code `ambiguous_account`), so the connection to act with is ambiguous. Keep one of them connected or move the others to a profile this key cannot access."},"422":{"x-summary":"There is no active Meta connection for this ad: reconnect the account.","description":"No active Meta connection for this ad. Reconnect the account."},"501":{"x-summary":"Only Meta ads support this operation, and a non-Meta `accountId` also fails: use a Meta ad and connection.","description":"Only supported on Meta (facebook/instagram). `accountId` naming a connection that is not Meta also answers 501."}}}},"/v1/ads/keywords/ideas":{"post":{"x-resource-group":"ads","operationId":"generateKeywordIdeas","tags":["Ad Insights"],"x-platforms":["google"],"summary":"Generate keyword ideas","description":"Suggests new keywords from seed keywords or a website using Google Keyword Planner, with search volume, competition and bid estimates.\n\nGoogle Ads only. Runs Keyword Planner's generateKeywordIdeas from seed keywords, a seed URL,\nor both, returning idea rows verbatim (avgMonthlySearches, competition, competitionIndex,\ntop-of-page bid micros, monthlySearchVolumes). Counters are int64s encoded as strings; bid\nvalues are micros of the account currency. Omitting `countries` targets worldwide.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string","description":"Zernio googleads SocialAccount id."},"adAccountId":{"type":"string","description":"Platform ad account ID (Google customer ID, digits only)."},"customerId":{"type":"string","deprecated":true,"description":"Alias of adAccountId, kept for existing callers"},"seedKeywords":{"type":"array","items":{"type":"string","maxLength":80},"minItems":1,"maxItems":20,"description":"Seed terms. Provide these, seedUrl, or both."},"seedUrl":{"type":"string","format":"uri","description":"Landing page to mine for ideas. Provide this, seedKeywords, or both."},"countries":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"minItems":1,"maxItems":10,"description":"ISO 3166-1 alpha-2 country codes. Omitted = worldwide."},"languageConstantId":{"type":"string","default":"1000","description":"Google languageConstant id (1000 = English)."},"network":{"type":"string","enum":["GOOGLE_SEARCH","GOOGLE_SEARCH_AND_PARTNERS"],"default":"GOOGLE_SEARCH"},"includeAdultKeywords":{"type":"boolean"},"pageSize":{"type":"integer","minimum":1,"maximum":10000},"pageToken":{"type":"string","description":"Cursor from paging.nextPageToken of the previous page."}}}}}},"responses":{"200":{"description":"Keyword idea rows (raw Keyword Planner shape)","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","description":"The customer the request ran against."},"data":{"type":"array","items":{"type":"object","description":"Raw GenerateKeywordIdeaResult: text + keywordIdeaMetrics."}},"aggregateMetricResults":{"type":["object","null"]},"paging":{"type":"object","properties":{"nextPageToken":{"type":["string","null"],"description":"Cursor for the next page; null when exhausted."}}}}}}}},"400":{"description":"Invalid input, or Google rejected the request; the message carries Google's error"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"x-summary":"A Zernio or Google Ads rate limit was reached: wait before retrying.","description":"Zernio Google Ads burst limit (15 requests per minute per connected account, 120 per minute per user) or a Google rate limit reached; the message says which and when to retry."},"501":{"description":"Only supported on Google Ads"}}}},"/v1/ads/keywords/historical-metrics":{"post":{"x-resource-group":"ads","operationId":"generateKeywordHistoricalMetrics","tags":["Ad Insights"],"x-platforms":["google"],"summary":"Get historical keyword metrics","description":"Gets historical search volume, competition and bid ranges for up to 1,000 keywords from Google Keyword Planner.\n\nGoogle Ads only. Runs Keyword Planner's generateKeywordHistoricalMetrics for up to 1,000\nexact keywords: historical search volume, competition and top-of-page bid ranges, plus\naverageCpcMicros when includeAverageCpc is set. Rows come back verbatim; counters are int64s\nencoded as strings, bid/CPC values are micros of the account currency.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","keywords"],"properties":{"accountId":{"type":"string","description":"Zernio googleads SocialAccount id."},"adAccountId":{"type":"string","description":"Platform ad account ID (Google customer ID, digits only)."},"customerId":{"type":"string","deprecated":true,"description":"Alias of adAccountId, kept for existing callers"},"keywords":{"type":"array","items":{"type":"string","maxLength":80},"minItems":1,"maxItems":1000},"countries":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"minItems":1,"maxItems":10,"description":"ISO 3166-1 alpha-2 country codes. Omitted = worldwide."},"languageConstantId":{"type":"string","default":"1000","description":"Google languageConstant id (1000 = English)."},"network":{"type":"string","enum":["GOOGLE_SEARCH","GOOGLE_SEARCH_AND_PARTNERS"],"default":"GOOGLE_SEARCH"},"includeAdultKeywords":{"type":"boolean"},"includeAverageCpc":{"type":"boolean","description":"Adds averageCpcMicros to each row's keywordMetrics."}}}}}},"responses":{"200":{"description":"Historical metric rows (raw Keyword Planner shape)","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","description":"The customer the request ran against."},"data":{"type":"array","items":{"type":"object","description":"Raw KeywordHistoricalMetricsResult: text, closeVariants, keywordMetrics."}},"aggregateMetricResults":{"type":["object","null"]}}}}}},"400":{"description":"Invalid input, or Google rejected the request; the message carries Google's error"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"x-summary":"A Zernio or Google Ads rate limit was reached: wait before retrying.","description":"Zernio Google Ads burst limit (15 requests per minute per connected account, 120 per minute per user) or a Google rate limit reached; the message says which and when to retry."},"501":{"description":"Only supported on Google Ads"}}}},"/v1/ads/insights":{"get":{"x-resource-group":"ads","operationId":"queryAdInsights","tags":["Ad Insights"],"x-platforms":["meta","google","tiktok"],"summary":"Flexible live insights query","description":"Runs a custom performance query against Meta, Google Ads or TikTok and returns the platform's rows as is, for reports the fixed endpoints don't cover. The account's platform picks the contract.\n\n### Meta (facebook/instagram)\n\nForwards caller-chosen `fields`, `breakdowns` and `filtering` to any Meta insights node and returns Meta's rows verbatim.\n\n- `objectId` (required) selects the node.\n- `level` sets row granularity.\n\nSemantic validation is Meta's: an unknown field or invalid breakdown combination returns a 400 carrying Meta's message. For long ranges or agency-scale accounts, prefer the async variant (POST /v1/ads/insights/reports).\n\n### Google Ads (googleads)\n\nRaw GAQL passthrough. Send any read-only GAQL SELECT via `query` (campaign/keyword/search-term/geo/demographic/asset/shopping resources, `change_event`, any `segments.*`). Rows come back verbatim (camelCase, counters as strings).\n\n- Results are paged at a fixed 10,000 rows; follow `paging.nextPageToken` with `pageToken`.\n- `adAccountId` (alias `customerId`) is only needed when the connection has several Google Ads accounts.\n\nSemantic validation is Google's: an invalid query returns a 400 carrying Google's message (note: selecting `segments.date` requires a finite date filter).\n\n#### GAQL version\n\nQueries run against Google Ads API **v25**, so write GAQL against the v25 field reference. One exception is translated for backward compatibility:\n\n- The legacy `campaign.start_date` / `campaign.end_date` (removed by Google in v23) are rewritten to `campaign.start_date_time` / `campaign.end_date_time`.\n- Rows still carry `campaign.startDate` / `campaign.endDate` as `YYYY-MM-DD`.\n- In WHERE, `=`, `<`, `<=`, `>`, `>=`, `BETWEEN` and `IS [NOT] NULL` against a `'YYYY-MM-DD'` literal are translated; any other form returns Google's 400.\n\nNew code should select the `_date_time` fields directly.\n\n### TikTok (tiktok/tiktokads)\n\nPassthrough of TikTok's synchronous report (`/report/integrated/get/`). Send:\n\n- `adAccountId`\n- `dataLevel`\n- `dimensions`\n- `metrics`\n- `fromDate`/`toDate` (TikTok caps the span at 365 days)\n- optionally `filtering`, in the same `[{\"field\", \"operator\", \"value\"}]` shape as Meta (operator is TikTok's `filter_type`, e.g. `IN`; array values are JSON-encoded for TikTok)\n\nRows come back verbatim as `{ dimensions, metrics }` with page-number paging.\n\n#### De-duplicated reach across a set of campaigns, ad groups or ads\n\nFilter the set and group by `country_code` instead of the entity id. TikTok then counts each person once across the whole set and range, per country.\n\nExample, two campaigns for a month:\n\n`dataLevel=AUCTION_CAMPAIGN&dimensions=country_code&metrics=reach,impressions,frequency&fromDate=2026-09-01&toDate=2026-09-30&filtering=[{\"field\":\"campaign_ids\",\"operator\":\"IN\",\"value\":[\"1876574798182050\",\"1876575504573650\"]}]`\n\n- For a set of ads use `dataLevel=AUCTION_AD` with `ad_ids`.\n- A filter on a finer entity than `dataLevel` (e.g. `ad_ids` at `AUCTION_CAMPAIGN`) returns 400: TikTok would otherwise widen it to every parent entity containing those ids.\n- `AUCTION_ADVERTISER` rejects entity filters.\n\nWhen the set delivers in several countries, reach is per country: summing the rows counts a person reached in two countries twice.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant); its platform selects the Meta, Google or TikTok contract."},{"name":"objectId","in":"query","schema":{"type":"string"},"description":"Meta only (required there): insights node (act_<n>, campaign id, ad set id or ad id)."},{"name":"query","in":"query","schema":{"type":"string","maxLength":10000},"description":"Google only (required there): the GAQL SELECT statement to run."},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"Google: platform ad account ID (Google customer ID, digits only) when the connection has several Google Ads accounts. TikTok (required there): the advertiser id."},{"name":"reportType","in":"query","schema":{"type":"string","enum":["BASIC","AUDIENCE"],"default":"BASIC"},"description":"TikTok only: report_type."},{"name":"dataLevel","in":"query","schema":{"type":"string","enum":["AUCTION_ADVERTISER","AUCTION_CAMPAIGN","AUCTION_ADGROUP","AUCTION_AD"]},"description":"TikTok only (required there): data_level."},{"name":"dimensions","in":"query","schema":{"type":"string"},"description":"TikTok only (required there): 1-4 comma-separated TikTok dimensions (e.g. country_code, campaign_id, stat_time_day)."},{"name":"metrics","in":"query","schema":{"type":"string"},"description":"TikTok only (required there): comma-separated TikTok metrics (e.g. reach,impressions,frequency,spend)."},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"TikTok only: page number."},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"TikTok only: rows per page."},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string"},"description":"Alias of adAccountId, kept for existing callers"},{"name":"pageToken","in":"query","schema":{"type":"string"},"description":"Google only: cursor from paging.nextPageToken of the previous page."},{"name":"level","in":"query","schema":{"type":"string","enum":["ad","adset","campaign","account"]},"description":"Row granularity"},{"name":"fields","in":"query","schema":{"type":"string"},"description":"Comma-separated Graph insights fields (e.g. spend,impressions,frequency,website_purchase_roas). Omitted = Meta's default set."},{"name":"breakdowns","in":"query","schema":{"type":"string"},"description":"Meta only: comma-separated Graph breakdowns (e.g. age,gender or publisher_platform). Returns 400 on TikTok (add the breakdown to dimensions with reportType=AUDIENCE, e.g. dimensions=campaign_id,placement) and on Google (select segments.* in the query)."},{"name":"actionBreakdowns","in":"query","schema":{"type":"string"},"description":"Comma-separated Graph action breakdowns; segments the actions[] arrays in each row. Pass `none` to clear Meta's default action_type breakdown, required to combine some non-action breakdowns such as instagram_ads_follow_type (otherwise Meta returns a (#100) invalid-combination error)."},{"name":"actionAttributionWindows","in":"query","schema":{"type":"string"},"description":"Comma-separated Meta attribution windows. Action values are returned keyed per window."},{"name":"actionReportTime","in":"query","schema":{"type":"string"},"description":"When actions are counted: impression, conversion or mixed."},{"name":"useUnifiedAttributionSetting","in":"query","schema":{"type":"boolean"},"description":"Use the ad sets' own attribution settings for action counting."},{"name":"filtering","in":"query","schema":{"type":"string"},"description":"JSON array of filter objects: [{\"field\", \"operator\", \"value\"}]. Applied server-side by Meta or TikTok (TikTok fields e.g. campaign_ids, adgroup_ids, ad_ids)."},{"name":"datePreset","in":"query","schema":{"type":"string"},"description":"Meta date_preset (e.g. last_7d, last_30d, this_month). Mutually exclusive with fromDate/toDate."},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Start of range (YYYY-MM-DD); requires toDate. Required on TikTok."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"End of range (YYYY-MM-DD); requires fromDate."},{"name":"timeIncrement","in":"query","schema":{"type":"string"},"description":"Days per row (1-90), monthly, or all_days."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":25},"description":"Rows per page"},{"name":"after","in":"query","schema":{"type":"string"},"description":"Cursor from paging.after of the previous page."}],"responses":{"200":{"description":"Insight rows (raw platform shape)","content":{"application/json":{"schema":{"type":"object","properties":{"objectId":{"type":"string","description":"Meta responses only."},"adAccountId":{"type":"string","description":"TikTok responses only: the advertiser queried."},"customerId":{"type":"string","description":"Google responses only: the customer the query ran against."},"fieldMask":{"type":["string","null"],"description":"Google responses only: the selected fields echoed by Google."},"data":{"type":"array","items":{"type":"object","description":"Raw platform row. Meta: keys are the requested Graph fields plus date_start/date_stop. Google: nested GAQL resources in camelCase, int64 counters as strings. TikTok: { dimensions, metrics } with metric values as strings."}},"paging":{"type":"object","properties":{"after":{"type":["string","null"],"description":"Meta cursor for the next page; null when exhausted."},"nextPageToken":{"type":["string","null"],"description":"Google cursor for the next page; null when exhausted."},"page":{"type":"integer","description":"TikTok only: current page."},"pageSize":{"type":"integer","description":"TikTok only."},"totalRows":{"type":"integer","description":"TikTok only."},"totalPages":{"type":"integer","description":"TikTok only."}}}}}}}},"400":{"x-summary":"The input is invalid or the platform rejected the query, such as an unknown field or malformed GAQL: correct the query.","description":"Invalid input, or the platform rejected the query (unknown field, invalid breakdown combo, malformed GAQL); the message carries the platform's error"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The TikTok connection cannot read that advertiser, or the ad account is not selected: use a connection with access or select it.","description":"TikTok: the connection cannot read that advertiser.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix it, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"x-summary":"A platform rate limit was reached, including every Meta throttle: wait for `Retry-After` before retrying.","description":"Platform rate limit reached. For Google this is the per-user burst limit or a Google rate limit; the message says which and when to retry. For Meta every throttle (codes 4, 17, 32, 613, 80000-80014) returns 429 `rate_limited` with `Retry-After`, even when Meta answers HTTP 400.","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the platform gives an estimate.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"501":{"description":"Only supported on Meta (facebook/instagram), Google Ads and TikTok"}}}},"/v1/ads/insights/reports":{"post":{"x-resource-group":"ads","operationId":"createAdInsightsReport","tags":["Ad Insights"],"x-platforms":["meta"],"summary":"Submit async insights report","description":"Starts a background Meta insights report for long date ranges or large accounts where a live query would be too slow.\n\nSame query surface as GET /v1/ads/insights, but\nin the JSON body; Meta processes the report server-side, which is the right choice for long\nranges or large accounts where the sync query is slow or rate-limited. Returns a `reportRunId`\nto poll via GET /v1/ads/insights/reports/{reportRunId}.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","objectId"],"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id (posting or ads variant)."},"objectId":{"type":"string","description":"Meta insights node: act_<n>, campaign id, ad set id or ad id."},"level":{"type":"string","enum":["ad","adset","campaign","account"]},"fields":{"type":"string","description":"Comma-separated Graph insights fields."},"breakdowns":{"type":"string","description":"Comma-separated Graph breakdowns."},"actionBreakdowns":{"type":"string","description":"Comma-separated Graph action breakdowns (e.g. action_type,action_destination). Pass `none` to clear Meta's default action_type breakdown, needed for some non-action breakdowns such as instagram_ads_follow_type."},"actionAttributionWindows":{"type":"array","items":{"type":"string"},"description":"Meta attribution windows (e.g. [\"7d_click\", \"1d_view\"]). Action values are returned keyed per window."},"actionReportTime":{"type":"string","description":"When actions are counted: impression, conversion or mixed."},"useUnifiedAttributionSetting":{"type":"boolean","description":"Use the ad sets' own attribution settings for action counting."},"filtering":{"type":"array","description":"Meta filter objects, applied server-side.","items":{"type":"object","required":["field","operator"],"properties":{"field":{"type":"string"},"operator":{"type":"string"},"value":{}}}},"datePreset":{"type":"string","description":"Mutually exclusive with fromDate/toDate."},"fromDate":{"type":"string","format":"date"},"toDate":{"type":"string","format":"date"},"timeIncrement":{"oneOf":[{"type":"integer","minimum":1,"maximum":90},{"type":"string","enum":["monthly","all_days"]}]}}}}}},"responses":{"202":{"description":"Report run submitted","content":{"application/json":{"schema":{"type":"object","properties":{"reportRunId":{"type":"string"},"status":{"type":"string","example":"Job Started"}}}}}},"400":{"description":"Invalid input, or Meta rejected the report parameters"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/MetaRateLimited"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/insights/reports/{reportRunId}":{"get":{"x-resource-group":"ads","operationId":"getAdInsightsReport","tags":["Ad Insights"],"x-platforms":["meta"],"summary":"Poll an async insights report run","description":"Checks progress of a background Meta insights report and returns its results once it has finished.\n\nStatus and results for a report run created via POST /v1/ads/insights/reports. While the job\nruns, returns `status` and `percentCompletion`. Once `status` is \"Job Completed\" the response\nalso carries a `data` page, cursor-paginated via `limit` / `after`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"reportRunId","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id used to resolve the Meta token (must be the same connection that created the run)."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":25}},{"name":"after","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Report run status (plus results when completed)","content":{"application/json":{"schema":{"type":"object","properties":{"reportRunId":{"type":"string"},"status":{"type":"string","description":"Meta async_status: Job Not Started, Job Started, Job Running, Job Completed, Job Failed, Job Skipped."},"percentCompletion":{"type":"integer"},"dateStart":{"type":"string"},"dateStop":{"type":"string"},"data":{"type":"array","items":{"type":"object"},"description":"Present only when status is Job Completed."},"paging":{"type":"object","properties":{"after":{"type":["string","null"]}}}}}}}},"400":{"description":"Invalid input, or the report run is not readable with this account's token"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/MetaRateLimited"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/{adId}/analytics":{"get":{"x-resource-group":"ads","operationId":"getAdAnalytics","tags":["Ad Insights"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit","microsoft"],"summary":"Get ad analytics","description":"Returns one ad's performance summary and daily timeline, with optional audience breakdowns on Meta, TikTok and LinkedIn.\n\nIt includes summary metrics, a daily timeline over the requested date range, and optional demographic breakdowns (Meta, TikTok and LinkedIn only). If no date range is provided, defaults to the last 90 days. Date range is capped at 730 days max.\n\n### History\n\nWhen an ad account connects, Zernio imports its last 90 days of metrics.\n\n- `summary` and `daily` come from those synced metrics, so they hold no data for days before that.\n- Breakdowns are read live from the platform over the requested range, so they are not limited by the import.\n\nWhen the ad belongs to a Meta ad account, a range reaching further back answers `202` with `backfillPending: true` and the covered part, while the older days (up to 730 days back) are imported in the background. Repeat the request until it returns 200.\n\nOther platforms never return `202`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adId","in":"path","required":true,"schema":{"type":"string"}},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"},"description":"Start of date range (YYYY-MM-DD). Defaults to 90 days ago."},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"},"description":"End of date range (YYYY-MM-DD). Defaults to today. Max 730-day range."},{"name":"breakdowns","in":"query","schema":{"type":"string"},"description":"Comma-separated breakdown dimensions.\n\n- **Meta**: age, gender, country, publisher_platform, device_platform, region, platform_position, impression_device, video_asset, image_asset, body_asset, title_asset.\n- **TikTok**: gender, age, country (or country_code), publisher_platform (or platform), ac, language, placement. TikTok serves at most 365 days per breakdown, so a longer range is read over its last 365 days and `analytics.breakdownsRange` says which window.\n- **LinkedIn** (firmographics): job_title, job_function, seniority, industry, company, company_size, country, region. Rows carry the raw pivot `value` plus a resolved `name`. Data is aggregated over the whole range, delayed 12-24h, and omits segments with fewer than 3 events.\n\n**Errors:**\n\n- A known dimension the platform cannot break down by is listed in `analytics.unsupportedBreakdowns` instead of being dropped (with guidance in `analytics.breakdownHints` where there is an alternative); the rest of the response is unchanged.\n- An unknown name returns 400.\n- A TikTok dimension that fails is listed in `analytics.breakdownErrors` and the response stays 200.\n- Metrics TikTok refuses for a dimension are listed in `analytics.breakdownDroppedMetrics`, and the row values derived from them are null.\n"}],"responses":{"200":{"description":"Ad analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdAnalyticsResponse"}}}},"202":{"x-summary":"Historical data is incomplete because the Meta backfill is still pending: retry later for the full history.","description":"Meta only. Historical data is incomplete and backfill remains pending.","headers":{"Retry-After":{"$ref":"#/components/headers/BackfillRetryAfter"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AdAnalyticsResponse"},{"type":"object","required":["backfillPending"],"properties":{"backfillPending":{"type":"boolean","description":"Always true on this response. Part of the requested range is still being backfilled; retry until the request returns 200."}}}]}}}},"400":{"x-summary":"A query parameter is invalid, such as an unknown breakdown dimension: the message lists the supported values.","description":"Invalid parameter (e.g. an unknown `breakdowns` dimension). The message lists the offending value(s) and the supported set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required: legacy plans need the Ads add-on, and usage-based plans include it by default.","description":"Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans."},"404":{"$ref":"#/components/responses/NotFound"},"409":{"x-summary":"Several active connections reach this ad account, so the target is ambiguous: keep only one connected for this key.","description":"Several active connections on the API key's profiles reach the ad account of this ad (code `ambiguous_account`), so the connection to act with is ambiguous. Keep one of them connected or move the others to a profile this key cannot access."},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"}}}},"/v1/ads/{adId}/tracking-tags":{"get":{"x-resource-group":"ads","operationId":"getAdTrackingTags","tags":["Tracking Tags"],"x-platforms":["meta","google","linkedin"],"summary":"Get ad tracking tags","description":"Shows the tracking parameters added to an ad's click URLs, such as UTM tags (not pixels).\n\nUnified read of the platform's native click-URL tracking params.\n- Meta (facebook/instagram): the creative's `url_tags` (and template_url_spec).\n- Google (googleads): the campaign's `trackingUrlTemplate` + `finalUrlSuffix`.\n- LinkedIn (linkedinads): the campaign's Dynamic UTM `dynamicValueParameters` + `customValueParameters`.\nReturns 405 for platforms without a click-URL tracking surface (TikTok, X, Pinterest).\n\n**Not pixels.** Despite the shared path segment, this endpoint has nothing to do with\nmeasurement tags. For an ad account's pixels use\n`GET /v1/accounts/{accountId}/tracking-tags?adAccountId=act_...` (Meta Pixels, with `kind`\nand `ownerAdAccountId`) or `GET /v1/accounts/{accountId}/conversion-destinations`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adId","in":"path","required":true,"schema":{"type":"string"},"description":"Ad id (hex _id, platformAdId, or effective story/media id)."}],"responses":{"200":{"description":"Tracking tags for the ad's platform (shape varies by platform).","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string"},"level":{"type":"string","enum":["creative","campaign"]},"urlTags":{"type":["string","null"],"description":"Meta: &-joined click-URL params."},"templateUrlSpec":{"type":["object","null"],"description":"Meta: third-party click-tracking template (Dynamic Ads)."},"trackingUrlTemplate":{"type":["string","null"],"description":"Google."},"finalUrlSuffix":{"type":["string","null"],"description":"Google."},"dynamicValueParameters":{"type":["object","null"],"description":"LinkedIn."},"customValueParameters":{"type":["object","null"],"description":"LinkedIn."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"description":"Ad not found"},"405":{"description":"Platform has no click-URL tracking surface"}}},"patch":{"x-resource-group":"ads","operationId":"updateAdTrackingTags","tags":["Tracking Tags"],"x-platforms":["meta","google","linkedin"],"summary":"Set ad tracking tags","description":"Sets the tracking parameters added to an ad's click URLs, such as UTM tags, without rebuilding the rest of the ad.\n\nSend only the fields for the ad's platform.\n\n### Meta\n\nSend `urlTags` (array of {key,value}). Meta creatives are immutable, so this rebuilds the creative and repoints the ad.\n\nBy DEFAULT we PRESERVE the existing creative verbatim (re-post its object_story_spec + the new url_tags, reusing the image). So you send `urlTags` ALONE, with no need to read back headline/body/CTA.\n\n`creative` (headline, body, callToAction, linkUrl, imageUrl) is OPTIONAL. It is only needed to rebuild explicitly, or for SHARE / page-post / dark / asset_feed creatives whose object_story_spec Meta strips (those return 422 asking for `creative`).\n\n### Google\n\nSend `trackingUrlTemplate` and/or `finalUrlSuffix` (full template strings; account quota applies).\n\nWritten at the CAMPAIGN level (the campaign's `tracking_url_template` / `final_url_suffix`), so the change applies to every ad in the ad's campaign.\n\n### LinkedIn\n\nSend `dynamicValueParameters` and/or `customValueParameters` (campaign-level Dynamic UTM).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"urlTags":{"type":"array","description":"Meta only. Click-URL params appended to a freshly-rebuilt creative. Meta dynamic macros ({{ad.id}}, {{campaign.id}}, {{placement}}, ...) are sent through unescaped so Meta expands them; every other character is percent-encoded.","items":{"type":"object","required":["key","value"],"properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"creative":{"type":"object","description":"Meta only. OPTIONAL: omit to preserve the existing creative verbatim (default). Provide it only to rebuild the creative explicitly, or for creatives whose object_story_spec Meta strips.","required":["headline","body","callToAction","linkUrl","imageUrl"],"properties":{"headline":{"type":"string"},"body":{"type":"string"},"callToAction":{"type":"string"},"linkUrl":{"type":"string","format":"uri"},"imageUrl":{"type":"string","format":"uri"},"videoUrl":{"type":"string","format":"uri"}}},"trackingUrlTemplate":{"type":"string","description":"Google only. Full tracking template (must contain {lpurl})."},"finalUrlSuffix":{"type":"string","description":"Google only. Parse-only key=value params."},"dynamicValueParameters":{"type":"object","additionalProperties":{"type":"string"},"description":"LinkedIn only. key -> dynamic value enum (CAMPAIGN_ID, CAMPAIGN_NAME, CREATIVE_ID, ...)."},"customValueParameters":{"type":"object","additionalProperties":{"type":"string"},"description":"LinkedIn only. key -> static value."}}}}}},"responses":{"200":{"x-summary":"The tags as they now stand are returned, with only the fields the platform supports.","description":"The tags as they now stand, in the same shape the GET on this path returns:\n`platform` plus the fields that platform supports. Meta returns `level`,\n`urlTags` and `templateUrlSpec`; Google returns `trackingUrlTemplate` and\n`finalUrlSuffix`. A field the platform does not support is absent.\n","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The free live ads limit is reached without a card, or the account is not selected: add a card or select it.","description":"Forbidden. Codes:\n\n- `ads_allowance_exceeded`: the team has no payment method on file and has reached the 500 free live ads. Add a card to resume.\n- `ad_account_not_selected`: the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"description":"Ad not found"},"405":{"description":"Platform has no click-URL tracking surface"},"422":{"description":"Meta creative cannot be rebuilt (e.g. placement-customized/asset-feed/dark creative)"},"429":{"$ref":"#/components/responses/MetaAdAccountWriteLimited"},"502":{"x-summary":"Meta accepted the request but failed to produce the image, for example from an upload or processing timeout.","description":"Meta accepted the request then failed to produce the media (upload session, chunk transfer, processing timeout, or a response with no image hash). Inspect `platformError.reason`."}}}},"/v1/ads/{adId}/comments":{"get":{"x-resource-group":"engagement","operationId":"getAdComments","tags":["Ad Accounts"],"x-platforms":["meta","tiktok"],"summary":"List comments on an ad","description":"Lists the comments on an ad's post, including dark posts that never ran organically, so you can moderate ad engagement.\n\nUseful for moderating or analyzing engagement on dark posts (ad creatives that never went live organically). The regular GET /v1/inbox/comments/{postId} endpoint cannot serve these because dark posts are not in Zernio's post database.\n\nRequires the Ads add-on. Response shape matches GET /v1/inbox/comments/{postId}.\n\n### Ad identifiers\n\nThe `{adId}` path segment accepts any identifier dialect Zernio indexes for the ad, so the caller doesn't need a translation step:\n\n- Zernio internal `_id` (24-char hex)\n- The numeric `platformAdId` (the value shipped in `comment.received` webhooks as `comment.ad.id`)\n- The creative's `effective_object_story_id` / `effective_instagram_media_id`\n\n### Meta (Facebook and Instagram)\n\nAn ad that runs on both Facebook feed and Instagram feed has two separate underlying posts with separate comment threads (the creative's effective_object_story_id and effective_instagram_media_id).\n\nUse the `placement` query param to pick one. With no param the Instagram side is returned when it exists, otherwise Facebook. The identifiers are read from the ad record (persisted during sync) with a Marketing-API fallback for ads that predate the field.\n\n#### Placement variants\n\nComments can land on extra posts Meta creates for placement variants, which the creative does not report. These are read too, merged newest first:\n\n- Instagram: every media a `comment.received` for this ad arrived on.\n- Facebook: every dark post matched to this ad by its copy.\n\nWith more than one post, `pagination.cursor` is a Zernio cursor covering all of them: pass it back unchanged.\n\n#### Instagram account requirement\n\nFor Instagram-placed comments, the Instagram account that runs the ad must be connected to Zernio, because those comments are read through that account's token.\n\nIf no connected Instagram account on the profile can read the ad's media, the call returns ads_connection_required. The Facebook side, if any, is still readable via ?placement=facebook.\n\n### TikTok\n\nTikTok uses the connected TikTok Ads advertiser token and supports both paid video ads and Spark Ads. `placement` is Meta-only and returns a 400 for TikTok.\n\n#### Date window and pagination\n\n`since` and `until` select a date window of at most 30 days; the default is the last 30 days.\n\nTikTok searches by ad group, so Zernio filters each page to this ad. A page can be empty while `pagination.hasMore` is true. Reuse `pagination.cursor` with the same `limit`; the cursor retains the date window.\n\n#### Lookups\n\nListing needs no identity or video item ID. `meta.tiktokItemId: null` does not prevent listing.\n\nWhen the ad group is stored, each page makes one comment-list call and no ad-detail lookup, including for external ads that TikTok no longer returns from ad details. If the ad group is missing, Zernio fetches ad details:\n\n- 404 ad_not_found: details are unavailable\n- 400 ad_not_commentable: no ad group\n\n#### Replies and moderation flags\n\nTikTok returns replies as separate comments with `parentId`; nested reply fetching is not supported.\n\n- `canReply`: requires a first-level comment, comment-management permission, a video item ID and a supported TT_USER or CUSTOMIZED_USER identity.\n- `canDelete`: requires TikTok's own-comment deletion capability, a video item ID and a supported identity.\n- `canHide`: true, because visibility changes need only advertiser and comment IDs.\n- `canLike`: false.\n\n`canReply` and `canDelete` are both false when identity or item is unknown. Listing uses stored and comment-specific fields without fetching identity. A direct reply or delete request can lazily resolve missing fields and succeed even after a false flag.\n\nUse the ad comment reply, hide and delete operations below to moderate TikTok comments.\n\n### Other platforms\n\nOther platforms return feature_not_available.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adId","in":"path","required":true,"schema":{"type":"string"},"description":"Internal Zernio ad ID or indexed platform ad/post ID."},{"name":"placement","in":"query","schema":{"type":"string","enum":["facebook","instagram"]},"description":"Which side of the ad to return comments for. Omit to default to the Instagram side when present, else Facebook. Returns ad_not_commentable if the ad has no such placement."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"since","in":"query","schema":{"type":"string","format":"date"},"description":"TikTok-only start date. Defaults to 30 days before until. Maximum window is 30 days."},{"name":"until","in":"query","schema":{"type":"string","format":"date"},"description":"TikTok-only end date. Defaults to today in UTC."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor from a previous response."}],"responses":{"200":{"description":"Comments on the ad.","content":{"application/json":{"schema":{"type":"object","required":["status","comments","pagination","meta"],"properties":{"status":{"type":"string","enum":["success"]},"comments":{"type":"array","items":{"type":"object","description":"Normalized comment. Same shape as /v1/inbox/comments/{postId} responses."}},"pagination":{"type":"object","properties":{"hasMore":{"type":"boolean"},"cursor":{"type":"string"}}},"meta":{"type":"object","required":["platform","adId","accountId","lastUpdated"],"properties":{"platform":{"type":"string","enum":["facebook","instagram","tiktok"],"description":"Platform of the comments."},"placement":{"type":"string","enum":["facebook","instagram"],"description":"The placement these comments are for, useful when you didn't pass ?placement= and want to know which one you got."},"adId":{"type":"string","description":"Internal Zernio ad ID."},"platformAdId":{"type":"string","description":"Platform ad ID."},"effectiveStoryId":{"type":"string","description":"Underlying post ID the comments belong to. effective_object_story_id for the Facebook side, effective_instagram_media_id for the Instagram side."},"tiktokItemId":{"type":["string","null"],"description":"TikTok-only video item ID from stored ad fields or returned comments. Null does not prevent listing; ad details are not fetched to populate it."},"since":{"type":"string","format":"date","description":"TikTok-only resolved start date."},"until":{"type":"string","format":"date","description":"TikTok-only resolved end date."},"facebookAccountId":{"type":["string","null"],"description":"Facebook-only. The connected Facebook Page SocialAccount these comments were read through. Pass it as `accountId` (with `effectiveStoryId` as the postId) to /v1/inbox/comments to reply/hide/delete. Null when no connected Page was used (then moderation isn't possible)."},"instagramUserId":{"type":"string","description":"Instagram-only. The Instagram-scoped business ID that owns the boosted media (creative.instagram_user_id)."},"instagramPermalink":{"type":"string","description":"Instagram-only. Public permalink of the boosted IG post (creative.instagram_permalink_url)."},"instagramAccountId":{"type":"string","description":"Instagram-only. The connected Instagram SocialAccount these comments were read through. Pass it as `accountId` (with `effectiveStoryId` as the postId) to /v1/inbox/comments to reply/hide/delete."},"accountId":{"type":"string","description":"Account ID (ads SocialAccount)."},"lastUpdated":{"type":"string","format":"date-time"}}}}},"example":{"status":"success","comments":[{"id":"7512345678901234567","message":"Can you share more details?","createdTime":"2026-09-08T10:00:00.000Z","from":{"id":"6123456789123456789","name":"reader","username":"reader","picture":"https://example.com/avatar.jpg","isOwner":false},"likeCount":4,"replyCount":0,"platform":"tiktok","url":null,"replies":[],"isHidden":false,"canReply":false,"canDelete":false,"canHide":true,"canLike":false,"isLiked":false}],"pagination":{"hasMore":false},"meta":{"platform":"tiktok","adId":"507f1f77bcf86cd799439011","platformAdId":"1790166588666881","accountId":"507f1f77bcf86cd799439012","tiktokItemId":null,"since":"2026-08-10","until":"2026-09-09","lastUpdated":"2026-09-09T12:00:00.000Z"}}}}},"400":{"x-summary":"The ad ID is invalid or the ad's creative has no commentable post: use a different ad.","description":"Invalid ad ID format, or the ad's creative format does not expose a commentable\nunderlying post (code ad_not_commentable).\n"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required, or the ad platform is not Meta or TikTok: use a supported ad.","description":"Ads access required (legacy plans need the Ads add-on; included by default on usage-based plans), or ad platform is not Meta or TikTok (code feature_not_available)."},"404":{"$ref":"#/components/responses/NotFound"},"422":{"x-summary":"The ads account token is unavailable, or no connected Instagram account can read the ad's media: reconnect and retry.","description":"Ads account token unavailable, or (for Instagram-placed ads) no connected\nInstagram account on the profile can read the ad's media (code ads_connection_required).\n"}}}},"/v1/ads/{adId}/comments/{commentId}/reply":{"post":{"x-resource-group":"engagement","operationId":"replyToAdComment","summary":"Reply to an ad comment","tags":["Ad Accounts"],"x-platforms":["tiktok"],"description":"Reply to a first-level TikTok ad comment. Replies to replies are rejected. The response commentId identifies the new reply.\n\nThis operation is not idempotent; do not blindly retry an uncertain response.\n\n### Requirements\n\n- Requires Ads access. The ad is resolved within the caller's accessible profiles.\n- Requires a TT_USER or CUSTOMIZED_USER identity with comment-management permission.\n\n### Identity resolution\n\nUnknown identity and video item fields are resolved only when needed for this action, then persisted for reuse. Comment-specific fields take precedence.\n\n- 404 ad_not_found: TikTok no longer returns the ad needed to resolve identity. Check deletion or archival in TikTok Ads Manager. Listing can still succeed.\n- 403 feature_not_available: unsupported or unavailable identity.\n- 403 insufficient_permissions: denied access to ad details, with reconnect guidance and the upstream platformError.\n\n### Comment verification\n\nBefore moderation, Zernio verifies that the comment belongs to this ad using TikTok's ad-group comment listing.\n\n- The default search window is the last 30 days.\n- Use since/until for older comments, with at most 30 days between the dates.\n- Lookups scan at most 2,000 ad-group comments; narrow the date window if exceeded.\n\n### Meta\n\nMeta returns 501 feature_not_available with guidance to use the existing inbox comment endpoints and the account/post IDs from GET /v1/ads/{adId}/comments.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adId","in":"path","required":true,"schema":{"type":"string"},"description":"Internal Zernio ad ID or indexed platform ad ID."},{"name":"commentId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"TikTok comment ID from the ad comment listing."},{"name":"since","in":"query","schema":{"type":"string","format":"date"},"description":"Start date of the comment lookup window. Defaults to 30 days before until."},{"name":"until","in":"query","schema":{"type":"string","format":"date"},"description":"End date of the comment lookup window. Defaults to today in UTC."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"description":"Non-empty reply text."}}},"example":{"text":"Thanks for your question!"}}}},"responses":{"200":{"description":"Comment action completed.","content":{"application/json":{"schema":{"type":"object","required":["status","commentId"],"properties":{"status":{"type":"string","enum":["success"]},"commentId":{"type":"string","description":"ID of the created reply or moderated comment."}}},"example":{"status":"success","commentId":"7512345678901234567"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The ads access or identity is unavailable, or TikTok denies permission: grant permission and reconnect the TikTok Ads account before retrying.","description":"Ads access or supported identity is unavailable (feature_not_available), or TikTok denies ad-detail access or comment-management permission (insufficient_permissions). Grant permission and reconnect the TikTok Ads account before retrying."},"404":{"x-summary":"The ad is unavailable on TikTok or the comment was not found in the date window: check the IDs.","description":"Ad is inaccessible or unavailable on TikTok for identity resolution (ad_not_found), or the comment was not found on this ad in the selected date window (resource_not_found)."},"422":{"description":"TikTok Ads connection is unavailable."},"501":{"x-summary":"Moderation on this route supports only TikTok: use the inbox comment routes for Meta.","description":"Moderation on this route supports TikTok. Use the inbox comment routes for Meta."},"502":{"x-summary":"TikTok rejected the request or was unavailable, so retry the request later.","description":"TikTok rejected the request or was unavailable. Inspect platformError for its code and message."}}}},"/v1/ads/{adId}/comments/{commentId}/hide":{"post":{"x-resource-group":"engagement","operationId":"hideAdComment","summary":"Hide or unhide an ad comment","tags":["Ad Accounts"],"x-platforms":["tiktok"],"description":"Hide or restore a TikTok ad comment. Send hidden=true to hide it or hidden=false to make it public again.\n\nIdentity and video item ID are not required; no identity lookup is performed.\n\nRequires Ads access. The ad is resolved within the caller's accessible profiles.\n\n### Comment lookup\n\nBefore moderation, Zernio verifies that the comment belongs to this ad using TikTok's ad-group comment listing.\n\n- The default search window is the last 30 days.\n- Use since/until for older comments, with at most 30 days between the dates.\n- Lookups scan at most 2,000 ad-group comments; narrow the date window if exceeded.\n\n### Meta\n\nMeta returns 501 feature_not_available with guidance to use the existing inbox comment endpoints and the account/post IDs from GET /v1/ads/{adId}/comments.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adId","in":"path","required":true,"schema":{"type":"string"},"description":"Internal Zernio ad ID or indexed platform ad ID."},{"name":"commentId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"TikTok comment ID from the ad comment listing."},{"name":"since","in":"query","schema":{"type":"string","format":"date"},"description":"Start date of the comment lookup window. Defaults to 30 days before until."},{"name":"until","in":"query","schema":{"type":"string","format":"date"},"description":"End date of the comment lookup window. Defaults to today in UTC."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["hidden"],"properties":{"hidden":{"type":"boolean","description":"True to hide the comment; false to restore it."}}},"example":{"hidden":true}}}},"responses":{"200":{"description":"Comment action completed.","content":{"application/json":{"schema":{"type":"object","required":["status","commentId"],"properties":{"status":{"type":"string","enum":["success"]},"commentId":{"type":"string","description":"ID of the created reply or moderated comment."},"hidden":{"type":"boolean","description":"The requested visibility state."}}},"example":{"status":"success","commentId":"7512345678901234567","hidden":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads access or the required TikTok comment capability is unavailable."},"404":{"description":"Ad is inaccessible or the comment was not found on this ad in the selected date window."},"422":{"description":"TikTok Ads connection is unavailable."},"501":{"x-summary":"Moderation on this route supports only TikTok: use the inbox comment routes for Meta.","description":"Moderation on this route supports TikTok. Use the inbox comment routes for Meta."},"502":{"x-summary":"TikTok rejected the request or was unavailable, so retry the request later.","description":"TikTok rejected the request or was unavailable. Inspect platformError for its code and message."}}}},"/v1/ads/{adId}/comments/{commentId}":{"delete":{"x-resource-group":"engagement","operationId":"deleteAdComment","summary":"Delete an ad comment","tags":["Ad Accounts"],"x-platforms":["tiktok"],"description":"Delete your own TikTok ad comment or reply. TikTok must return can_delete=true for the comment. Other users' comments can be hidden instead.\n\nRequires Ads access. The ad is resolved within the caller's accessible profiles.\n\n### Identity resolution\n\nUnknown identity and video item fields are resolved only when needed for this action, then persisted for reuse. Comment-specific fields take precedence.\n\n### Comment lookup\n\nBefore moderation, Zernio verifies that the comment belongs to this ad using TikTok's ad-group comment listing.\n\n- The default search window is the last 30 days.\n- Use since/until for older comments, with at most 30 days between the dates.\n- Lookups scan at most 2,000 ad-group comments; narrow the date window if exceeded.\n\n### Errors\n\n- 404 ad_not_found: TikTok no longer returns the ad needed to resolve identity. Check deletion or archival in TikTok Ads Manager. Listing can still succeed.\n- 403 feature_not_available: unsupported or unavailable identity.\n- 403 insufficient_permissions: denied access to ad details. Comes with reconnect guidance and the upstream platformError.\n- 501 feature_not_available (Meta): with guidance to use the existing inbox comment endpoints and the account/post IDs from GET /v1/ads/{adId}/comments.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"adId","in":"path","required":true,"schema":{"type":"string"},"description":"Internal Zernio ad ID or indexed platform ad ID."},{"name":"commentId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"TikTok comment ID from the ad comment listing."},{"name":"since","in":"query","schema":{"type":"string","format":"date"},"description":"Start date of the comment lookup window. Defaults to 30 days before until."},{"name":"until","in":"query","schema":{"type":"string","format":"date"},"description":"End date of the comment lookup window. Defaults to today in UTC."}],"responses":{"200":{"description":"Comment action completed.","content":{"application/json":{"schema":{"type":"object","required":["status","commentId"],"properties":{"status":{"type":"string","enum":["success"]},"commentId":{"type":"string","description":"ID of the created reply or moderated comment."}}},"example":{"status":"success","commentId":"7512345678901234567"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access, own-comment deletion or identity support is unavailable, or TikTok denies ad access: check permissions.","description":"Ads access, own-comment deletion or supported identity is unavailable (feature_not_available), or TikTok denies ad-detail access (insufficient_permissions)."},"404":{"x-summary":"The ad is unavailable on TikTok or the comment was not found in the date window: check the IDs.","description":"Ad is inaccessible or unavailable on TikTok for identity resolution (ad_not_found), or the comment was not found on this ad in the selected date window (resource_not_found)."},"422":{"description":"TikTok Ads connection is unavailable."},"501":{"x-summary":"Moderation on this route supports only TikTok: use the inbox comment routes for Meta.","description":"Moderation on this route supports TikTok. Use the inbox comment routes for Meta."},"502":{"x-summary":"TikTok rejected the request or was unavailable, so retry the request later.","description":"TikTok rejected the request or was unavailable. Inspect platformError for its code and message."}}}},"/v1/ads/business-centers":{"get":{"x-resource-group":"ads","operationId":"listAdsBusinessCenters","tags":["Ad Accounts"],"x-platforms":["tiktok"],"summary":"List TikTok Business Centers","description":"Returns the TikTok Business Centers (BCs) the connected `tiktokads` account can read.\nEach BC reports its advertiser count so callers can build agency-style pickers\nwithout re-walking `/v1/ads/accounts` per BC.\n\nTikTok-only. Solo advertisers (non-agency tokens) return an empty array.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"ID of the `tiktokads` (or parent `tiktok` posting) SocialAccount"}],"responses":{"200":{"description":"Business centers","content":{"application/json":{"schema":{"type":"object","properties":{"businessCenters":{"type":"array","items":{"$ref":"#/components/schemas/BusinessCenter"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"description":"TikTok Ads not connected"}}}},"/v1/ads/alerts":{"get":{"x-resource-group":"ads","operationId":"listAdsAlerts","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"List ads that need attention","description":"Lists what needs attention across your ads, most severe first:\n\n- ads created in the last 90 days that were rejected\n- campaigns the platform reports delivery issues on\n- Meta ad accounts with a failed or overdue payment, or disabled while holding live ads\n- campaigns that spent on 3 or more of the last 7 days without a result (conversion, lead, purchase or conversation goals)\n- budgets spent to their daily cap yesterday\n- ads connections that need reconnecting while they still hold live ads\n- ad accounts whose sync has been failing\n\nBuilt from stored data and the last 7 days of synced metrics, so it costs no platform call.\n\nEach alert has a stable `id`. Dismiss one with `POST /v1/ads/alerts/{alertId}/dismiss` to hide it for 30 days.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Only alerts of this ads connection (sibling-expanded like /v1/ads/tree). Omit for every ad account the API key can reach."},{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Only alerts of the ads connections on this profile. Omit for every profile the API key can reach."},{"name":"includeDismissed","in":"query","schema":{"type":"boolean","default":false},"description":"Also return dismissed alerts, with `dismissed: true`."}],"responses":{"200":{"description":"Alerts, most severe first.","content":{"application/json":{"schema":{"type":"object","properties":{"alerts":{"type":"array","items":{"$ref":"#/components/schemas/AdsAlert"}},"counts":{"type":"object","description":"Open (not dismissed) alerts per severity.","properties":{"error":{"type":"integer"},"warning":{"type":"integer"},"info":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required: legacy plans need the Ads add-on, and usage-based plans include it by default.","description":"Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans."},"429":{"$ref":"#/components/responses/AnalyticsRateLimited"}}}},"/v1/ads/alerts/{alertId}/dismiss":{"post":{"x-resource-group":"ads","operationId":"dismissAdsAlert","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"Dismiss an ads alert","description":"Hides an alert from `GET /v1/ads/alerts` for 30 days for the calling user. If the problem is still there after\nthat, the alert comes back.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"alertId","in":"path","required":true,"schema":{"type":"string","maxLength":200},"description":"The `id` of an alert from GET /v1/ads/alerts."}],"responses":{"200":{"description":"Dismissed.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"dismissed":{"type":"boolean"},"dismissedUntil":{"type":"string","format":"date-time"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required: legacy plans need the Ads add-on, and usage-based plans include it by default.","description":"Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans."},"503":{"description":"Dismissing is temporarily unavailable (code `feature_not_available`)."}}}},"/v1/ads/activity":{"get":{"x-resource-group":"ads","operationId":"getAdsActivityLog","tags":["Ad Accounts"],"x-platforms":["meta","google"],"summary":"Ad account change / audit log","description":"Shows who changed what in an ad account and when, as an audit log of edits to campaigns, ad sets and ads.\n\n### Google\n\nReads the customer's `change_event` history, newest first. `adAccountId` is the numeric customer id.\n\nGoogle keeps 30 days of it, so `since` defaults to 29 days ago and an older `since` returns 400. `until` defaults to today.\n\nEach change is mapped onto the Meta row shape:\n\n- `event_type` = resource_change_operation (CREATE, UPDATE, REMOVE)\n- `event_time` = change_date_time\n- `actor_name` = user_email\n- `object_type` = change_resource_type\n- `object_id` = the last numeric id of `object_resource_name`\n- `application_name` = client_type\n- `changed_fields` (array)\n- `extra_data` = a JSON string `{ old, new }` with Google's old and new resource\n\n#### Pagination\n\nPass `paging.after` back as `after` for the next page; it is null when nothing older is left.\n\nA page never splits a change batch (the changes of one request share an `event_time`). So a page can hold fewer rows than `limit` while more follow, or more when one batch is larger than `limit`.\n\n### Meta\n\nAccount-level audit log from Meta's `/act_X/activities`: who changed what and when (creates, edits, status flips, budget changes...). Includes Meta's translated event names and the structured before/after in `extra_data`. Rows are returned verbatim.\n\nMeta has no server-side per-object filter on this edge, so `objectId` filters the returned page client-side. Combine it with paging to walk history for one campaign/ad set/ad.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"Meta ad account id (act_<n>), or the Google customer id (digits only)."},{"name":"since","in":"query","schema":{"type":"string","format":"date"},"description":"Start of range (YYYY-MM-DD). Google: at most 29 days ago, the default."},{"name":"until","in":"query","schema":{"type":"string","format":"date"},"description":"End of range (YYYY-MM-DD)."},{"name":"objectId","in":"query","schema":{"type":"string"},"description":"Client-side filter to one object id (campaign, ad set / ad group or ad)."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Rows per page"},{"name":"after","in":"query","schema":{"type":"string"},"description":"Cursor from paging.after of the previous page."}],"responses":{"200":{"description":"Activity rows (raw Meta shape; Google changes mapped onto it)","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"data":{"type":"array","items":{"type":"object","description":"Raw Meta activity row: event_type, translated_event_type, event_time, actor_name, object_id, object_name, object_type, application_name, extra_data (JSON string with before/after). Google rows carry event_type, event_time, actor_name, object_id, object_type, object_resource_name, application_name, changed_fields and extra_data (see the description)."}},"paging":{"type":"object","properties":{"after":{"type":["string","null"],"description":"Cursor for the next page; null when exhausted."}}}}}}}},"400":{"description":"Invalid input, a Google since older than 30 days, or the platform rejected the query"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram) and Google"}}}},"/v1/ads/rf-predictions":{"post":{"x-resource-group":"ads","operationId":"createRfPrediction","tags":["Reach and Frequency"],"x-platforms":["meta"],"summary":"Create reach-frequency prediction","description":"Quotes the reach or budget for a Meta reach and frequency campaign over a date range, without buying anything.\n\nThis is a QUOTE: nothing is bought and no ad entities are created. Provide a date range plus exactly one of:\n\n- `budgetAmount`: Meta predicts reach\n- `reach`: Meta predicts the budget\n\nThe response carries the estimate and its allowed bounds (min/max budget and reach).\n\n### Buying\n\nPredictions expire on their own. To buy:\n\n1. Reserve one via POST /v1/ads/rf-predictions/{predictionId}/reserve.\n2. Pass the RESERVED id to POST /v1/ads/create with `buyingType: \"RESERVED\"`.\n\n### Placements\n\nReservation campaigns reject automatic placements.\n\n- Top-level `placements` wins.\n- When it is omitted, `targeting.placements` is used.\n- When neither is set, placements default to Facebook feed (+ Instagram stream when a linked IG professional account resolves).\n\nInstagram placements require that IG account.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","adAccountId","startDate","endDate"],"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id (posting or ads variant)."},"adAccountId":{"type":"string","description":"Platform ad account id (Meta act_<n>, Google customer id, LinkedIn account id, ...)."},"budgetAmount":{"type":"number","description":"Whole currency units. Exactly one of budgetAmount / reach."},"reach":{"type":"integer","description":"Target unique reach. Exactly one of budgetAmount / reach."},"startDate":{"type":"string","format":"date-time","description":"Campaign window start (must be in the future)."},"endDate":{"type":"string","format":"date-time"},"frequencyCap":{"type":"integer","minimum":1,"maximum":90,"description":"Max impressions per person over the window."},"targeting":{"type":"object","description":"Canonical camelCase TargetingSpec (same shape as /v1/ads/create's `targeting`). Defaults to countries: [US]."},"placements":{"type":"object","description":"Meta placements object (same shape as /v1/ads/create's `placements`)."}}}}}},"responses":{"201":{"description":"Prediction created (usually ready within seconds)","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"currency":{"type":"string"},"prediction":{"$ref":"#/components/schemas/RfPrediction"}}}}}},"400":{"description":"Invalid input, or Meta rejected the prediction; the message carries Meta's error"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"description":"No Facebook Page resolved for the account"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/rf-predictions/{predictionId}":{"get":{"x-resource-group":"ads","operationId":"getRfPrediction","tags":["Reach and Frequency"],"x-platforms":["meta"],"summary":"Get reach-frequency prediction","description":"Shows a Meta reach and frequency prediction, with its estimate and status.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"predictionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Prediction status and estimates","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"currency":{"type":"string"},"prediction":{"$ref":"#/components/schemas/RfPrediction"}}}}}},"400":{"description":"Invalid input"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}},"delete":{"x-resource-group":"ads","operationId":"cancelRfReservation","tags":["Reach and Frequency"],"x-platforms":["meta"],"summary":"Cancel reach-frequency booking","description":"Cancels a Meta reach and frequency reservation, releasing its locked price and inventory.\n\nUnreserved predictions expire on their own.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"predictionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Reservation cancelled"},"400":{"description":"Invalid input, or Meta rejected the cancel"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/rf-predictions/{predictionId}/reserve":{"post":{"x-resource-group":"ads","operationId":"reserveRfPrediction","tags":["Reach and Frequency"],"x-platforms":["meta"],"summary":"Reserve reach-frequency inventory","description":"Locks the quoted price and inventory of a Meta reach and frequency prediction so you can launch a campaign on it.\n\nLocks the quoted price + inventory until the returned `expiresAt` and mints a NEW\nprediction id. Pass that RESERVED id (not the original) as `rfPredictionId` on\nPOST /v1/ads/create. Release an unused reservation via DELETE.","security":[{"bearerAuth":[]}],"parameters":[{"name":"predictionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","adAccountId"],"properties":{"accountId":{"type":"string"},"adAccountId":{"type":"string"}}}}}},"responses":{"201":{"description":"Reserved; `prediction.predictionId` is the new RESERVED id","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"prediction":{"$ref":"#/components/schemas/RfPrediction"}}}}}},"400":{"description":"Invalid input, or Meta rejected the reserve"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/studies":{"get":{"x-resource-group":"ads","operationId":"listAdStudies","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"A/B tests and lift studies","description":"Lists the A/B tests and lift studies on a Meta ad account, with their timing and test groups.\n\nLists the ad account's A/B tests and lift studies (Meta's `/act_X/ad_studies`), rows\nreturned verbatim. The default projection covers id, name, type, timing and cells with\nsplit percentages; `fields` is a raw-passthrough override.","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"Meta ad account id (act_<n>)."},{"name":"fields","in":"query","schema":{"type":"string","example":"id,name,type,cells{id,name,treatment_percentage}"},"description":"Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers, so a nested edge can be paged explicitly: without a .limit() modifier the expansion runs at the Meta default page size and the tail is dropped silently."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Rows per page"},{"name":"after","in":"query","schema":{"type":"string"},"description":"Cursor from paging.after of the previous page."}],"responses":{"200":{"description":"Ad studies (raw Meta shape)","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"data":{"type":"array","items":{"type":"object","description":"Raw Meta ad study row."}},"paging":{"type":"object","properties":{"after":{"type":["string","null"],"description":"Cursor for the next page; null when exhausted."}}}}}}}},"400":{"description":"Invalid input, or Meta rejected the query"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/tiktok-identities":{"get":{"x-resource-group":"ads","operationId":"listAdsTikTokIdentities","tags":["Ad Creatives"],"x-platforms":["tiktok"],"summary":"List TikTok ad identities","description":"Lists the identities an ad on this TikTok advertiser may run as (the profile shown on the ad):\n\n- the advertiser's own TikTok accounts (TT_USER)\n- Business Center authorized accounts (BC_AUTH_TT)\n- custom brand identities (CUSTOMIZED_USER)\n\nPass the chosen `identityId` on POST /v1/ads/create or POST /v1/ads/boost. Spark-post identities (AUTH_CODE) are not listed; a Spark code creates its own.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"A tiktok or tiktokads account ID"},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"TikTok advertiser ID"}],"responses":{"200":{"description":"Identities","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"identities":{"type":"array","items":{"type":"object","properties":{"identityId":{"type":"string"},"identityType":{"type":"string","enum":["TT_USER","BC_AUTH_TT","CUSTOMIZED_USER"]},"displayName":{"type":["string","null"]},"username":{"type":["string","null"]},"profileImage":{"type":["string","null"]},"identityAuthorizedBcId":{"type":["string","null"],"description":"Business Center that authorized a BC_AUTH_TT identity"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/ads/tiktok-smart-plus-materials":{"get":{"x-resource-group":"ads","operationId":"getTikTokSmartPlusMaterialReport","tags":["Ad Insights"],"x-platforms":["tiktok"],"summary":"Per-creative performance inside TikTok Smart+ ads","description":"Breaks a Smart+ ad (or ad group) down by creative material, one row per Spark post, video or image, from TikTok's Smart+ material report. For a Spark post `tiktokItemId` is the TikTok post id.\n\n### Metrics\n\nConversion metrics are TikTok web (pixel) events. `purchases`, `purchaseValue` and `roas` come from Complete Payment, or from Place an Order (legacy ON_WEB_ORDER pixels) when that reports more; the two are never summed.\n\nMetrics TikTok returns empty come back as null.\n\n### Rows\n\nTikTok allows two dimensions per report, so rows are keyed by the Smart+ ad (`level=ad`) or by the ad group (`level=adGroup`), not both.\n\n- At `level=ad` a row is identified by `smartPlusAdId` + `materialId`.\n- At `level=adGroup` a row is identified by `adGroupId` + `materialId`.\n\nEach row appears once across all pages.\n\n### Sorting and paging\n\nRows are sorted by `spend` descending, then the Smart+ ad or ad group id, then `materialId`.\n\nThe full result is cached for 10 minutes per account, advertiser and query. So pages read within that window are consistent and `totalRows` counts distinct rows.\n\n### How rows are read\n\n- When the unfiltered report fits one page (100 rows or fewer), it is served as is.\n- When the result spans more than one TikTok page, it is read per Smart+ ad (or ad group) listed on the advertiser, every status included. Those reads can return more rows than TikTok's unfiltered report declares, so `totalRows` can be larger than that count.\n\n### Short reads\n\nEach TikTok read is checked against the row count it declares itself, and a short read is retried once.\n\n- A shortfall of at most 2 rows (or 1% of the rows, whichever is more) is served with `missingRows` set to that number.\n- A larger one answers 502 instead of a short result.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"A tiktok or tiktokads account ID"},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"TikTok advertiser ID"},{"name":"startDate","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"YYYY-MM-DD, in the advertiser's time zone"},{"name":"endDate","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"YYYY-MM-DD, on or after startDate"},{"name":"level","in":"query","required":false,"schema":{"type":"string","enum":["ad","adGroup"],"default":"ad"},"description":"Key each row by Smart+ ad or by ad group"},{"name":"smartPlusAdIds","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated Smart+ ad ids to filter by (up to 100)"},{"name":"adGroupIds","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated ad group ids to filter by (up to 100)"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}}],"responses":{"200":{"description":"Material rows","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"level":{"type":"string","enum":["ad","adGroup"]},"startDate":{"type":"string"},"endDate":{"type":"string"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalRows":{"type":"integer"},"totalPages":{"type":"integer"},"missingRows":{"type":"integer","description":"Rows TikTok declared that a read and its retry could not return. 0 when the result is complete."},"rows":{"type":"array","items":{"type":"object","properties":{"materialId":{"type":"string","description":"TikTok main material id"},"materialType":{"type":["string","null"],"description":"e.g. VIDEO_SPARK_ADS, VIDEO, IMAGE"},"tiktokItemId":{"type":["string","null"],"description":"The TikTok post id when the material is a Spark post"},"name":{"type":["string","null"],"description":"Material name or post caption"},"smartPlusAdId":{"type":["string","null"],"description":"Set when level=ad"},"adGroupId":{"type":["string","null"],"description":"Set when level=adGroup"},"metrics":{"type":"object","properties":{"spend":{"type":["number","null"]},"impressions":{"type":["number","null"]},"clicks":{"type":["number","null"]},"cpc":{"type":["number","null"]},"addToCart":{"type":["number","null"]},"initiateCheckout":{"type":["number","null"]},"addPaymentInfo":{"type":["number","null"]},"purchases":{"type":["number","null"]},"purchaseValue":{"type":["number","null"]},"roas":{"type":["number","null"]}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"accountId is not a TikTok or TikTok Ads connection (code feature_not_available)."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"description":"The TikTok connection has no TikTok Ads token: connect TikTok Ads first (code ads_connection_required)."},"502":{"x-summary":"TikTok returned incomplete Smart+ data: retry later, and pass smartPlusAdIds or adGroupIds for advertisers with over 2,000 Smart+ ads.","description":"Retry later. Returned when:\n\n- more rows than the tolerance (2, or 1% of the rows) were missing from TikTok's material report after a retry (`details` carries `totalNumber`, `distinctRows` and `missingRows`); or\n- TikTok's Smart+ ad listing returned fewer ads than it declared (`details` carries `declaredAds`, `listedAds` and `listingTruncated`).\n\nWith `listingTruncated`, the advertiser has more than 2,000 Smart+ ads, so pass `smartPlusAdIds` or `adGroupIds`."}}}},"/v1/ads/tiktok-smart-plus-reviews":{"get":{"x-resource-group":"ads","operationId":"listTikTokSmartPlusReviews","tags":["Ad Campaigns"],"x-platforms":["tiktok"],"summary":"Review status of every TikTok Smart+ ad of an advertiser","description":"Returns the review verdict of every Upgraded Smart+ ad of one TikTok advertiser, with each creative's verdict, in one paginated read.\n\nUse it to refresh reviews periodically: one call (plus its pages) per advertiser per refresh, instead of `GET /v1/ads/{adId}/tiktok-smart-plus-review` per ad.\n\n### How Zernio reads TikTok\n\n1. Zernio lists the advertiser's Smart+ ads with `/smart_plus/ad/get/` (deleted ones only with `includeDeleted=true`).\n2. It reads `/smart_plus/ad/review_info/` for Smart+ ads holding up to 50 creatives in total per call (TikTok refuses more). A Smart+ ad with more than 50 creatives is read alone.\n3. Calls run across ad groups, one after another while TikTok accepts them, for up to 20 seconds per request. Ads not reached are read by the next request, which can come right away.\n\nOne request per advertiser and connection refreshes at a time. A parallel request sends no review call and answers what is stored with `refreshState: paused` and `retryAfterSeconds: 20`.\n\nA full refresh of N Smart+ ads with C creatives in total costs about `ceil(N / 100)` listing calls and `ceil(C / 50)` review calls on TikTok.\n\nWhen TikTok still refuses a call for its creative count, Zernio lowers the creative cap for that advertiser and reads the same ads again in smaller calls, never resending the refused size.\n\n### Stale while refreshing\n\nEvery review is stored for 24 hours per connection, advertiser and Smart+ ad (shared with the single-ad read). `readAt` is always the time TikTok answered, never rewritten when served from the store.\n\n`maxAgeSeconds` (default 3600) is the freshness window:\n\n- A review read within it is fresh and costs no TikTok call.\n- An older one is still returned in `items` but is read again.\n- A Smart+ ad never read is also read.\n\nEach request alternates one batch of Smart+ ads never read (live, then deleted with `includeDeleted=true`) with one batch of stale ones, oldest `readAt` first.\n\nSo a quota pause starves neither, progress carries over between requests, and an ad already read never goes back to pending. A stored review is replaced only by a successful read.\n\n### Response fields\n\n- `counts`: splits the Smart+ ads on this page into `fresh`, `stale`, `pending` and `failed`.\n- `oldestReadAt`: the oldest `readAt` of `items`.\n- `incomplete`: true only while some Smart+ ad of the page has never been read (`pending > 0`).\n- `allFresh`: staleness is reported apart. True when every item and refusal of the page is within `maxAgeSeconds` and nothing is pending.\n- `refreshState`: `paused` or `refused` when Zernio could not refresh some due ads of the page because review reads are held or TikTok refused them over quota.\n- `retryAfterSeconds` (also in the `Retry-After` header): when that later read can reach TikTok, even with nothing pending.\n\nA page with stale items and nothing pending is complete (`incomplete: false`). Move on, and a later read refreshes it oldest first.\n\nOn 2026-10-25 TikTok's quota allowed about 130 to 230 Smart+ ads per advertiser per hour (about 11.5 ads and 4 creatives per successful call). A larger advertiser cannot be fully refreshed within one hour, so its pages stay complete but not `allFresh`.\n\n### Listing freshness\n\nThe listing is stored with the time it was read (`listing.readAt`) and listed again when it is older than `maxAgeSeconds`. So it can be up to `maxAgeSeconds` old: a Smart+ ad created on TikTok appears after at most that long (one hour by default).\n\n- `listing.source: fresh`: the listing was read within `maxAgeSeconds`.\n- `listing.source: fallback`: relisting failed, so Zernio serves the stored listing, with the relist error in `listing.error`, instead of failing the request.\n\nOnly when no listing was ever stored does the listing error fail the request.\n\n### Review quota\n\nTikTok's review endpoint has a strict quota of its own (TikTok documents neither the quota nor its scope). One request keeps reading batches (up to 50 creatives each) while TikTok accepts them.\n\nZernio may hold review reads after an overage: about 60 seconds, then 120 and up to 240 while TikTok keeps refusing, and about 60 again after a successful call, each with up to 10% of random jitter.\n\nWhen TikTok is over quota (or reads are held), Zernio stops calling TikTok and answers 200 with the reviews it has:\n\n- stale reviews in `items`\n- the Smart+ ads never read in `pendingSmartPlusAdIds`\n- `incomplete: true` when any are pending\n- `refreshState` (`paused` or `refused`) with `retryAfterSeconds` (also in the `Retry-After` header) whenever due ads were left unread\n\nEvery Smart+ ad of the page is in `items`, `failedSmartPlusAds` or `pendingSmartPlusAdIds`. Wait `retryAfterSeconds` and read the same page again: only the stale and pending ads reach TikTok.\n\n### Refused ads\n\nA Smart+ ad whose review TikTok refuses on its own (for example one deleted on TikTok since the listing was read) is returned in `failedSmartPlusAds` with TikTok's error and `refusedAt`. The rest of the page is still read.\n\nZernio finds it by splitting the refused batch in halves, at most 16 extra TikTok calls per page. Ads still unresolved after that keep their stored review, or stay in `pendingSmartPlusAdIds` when they have none, and are read again by the next request, in turn with the other due ads.\n\nA refusal of a single ad is stored for 24 hours and read again once it is older than `maxAgeSeconds`. When an ad has both a stored review and a stored refusal, the more recent one is returned.\n\nWhen both halves of a refused batch are refused with the same TikTok error (for example a permission error), Zernio stops calling TikTok for that page:\n\n- If every Smart+ ad of the page has a stored review or refusal, it serves them and returns the refusal in `reviewError`.\n- If some ad was never read, the whole request fails with that error.\n\n### Paging\n\nItems are sorted by `adGroupId`, then `smartPlusAdId`, so pages are stable.\n\nKeep one page in flight per advertiser and read its pages one after another. Parallel pages of one advertiser spend its review quota at the same time and come back incomplete.\n\nProduction logs suggest the quota is counted per advertiser (not confirmed by TikTok), so different advertisers have been read in parallel without throttling each other.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"A tiktok or tiktokads account ID"},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"TikTok advertiser ID"},{"name":"includeDeleted","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Also return Smart+ ads deleted on TikTok (listed with `primary_status: STATUS_ALL`)."},{"name":"maxAgeSeconds","in":"query","required":false,"schema":{"type":"integer","minimum":600,"maximum":86400,"default":3600},"description":"Freshness window in seconds. Reviews, refusals and the listing read within it are served without calling TikTok; older ones are still returned but read again, oldest first."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":500}}],"responses":{"200":{"x-summary":"One page of Smart+ ad reviews is returned: check `incomplete` because true means some ads were never read.","description":"The reviews of one page of the advertiser's Smart+ ads. Check `incomplete`: when true, some Smart+ ads of the page were never read. `allFresh` says whether every review is within `maxAgeSeconds`.","headers":{"Retry-After":{"description":"Present only when `refreshState` is `paused` or `refused`: seconds until Zernio calls TikTok's review endpoint for this advertiser and connection again. Same value as `retryAfterSeconds`.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"includeDeleted":{"type":"boolean"},"maxAgeSeconds":{"type":"integer","description":"The freshness window this page was read with."},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"},"totalSmartPlusAds":{"type":"integer","description":"Smart+ ads of the advertiser across all pages."},"listing":{"type":"object","description":"The Smart+ ad listing this page was cut from.","properties":{"readAt":{"type":"string","format":"date-time","description":"When the listing was read from TikTok."},"source":{"type":"string","enum":["fresh","fallback"],"description":"`fresh`: read within `maxAgeSeconds`. `fallback`: relisting failed and this is the older stored listing."},"error":{"type":["object","null"],"description":"The relist error on a fallback, otherwise null.","properties":{"tiktokCode":{"type":["integer","null"]},"message":{"type":"string"}}}}},"reviewError":{"type":["object","null"],"description":"Set when TikTok refused both halves of a review batch the same way (for example a permission error) and the page was served from stored reviews instead of being refreshed. Null otherwise.","properties":{"tiktokCode":{"type":["integer","null"]},"message":{"type":"string"}}},"counts":{"type":"object","description":"The Smart+ ads on this page split by state; the four counts add up to the Smart+ ads on this page (fewer than `pageSize` on the last page).","properties":{"fresh":{"type":"integer","description":"Items read within `maxAgeSeconds`."},"stale":{"type":"integer","description":"Items read earlier, returned with their `readAt` and due for a refresh."},"pending":{"type":"integer","description":"Smart+ ads never read (`pendingSmartPlusAdIds`)."},"failed":{"type":"integer","description":"Entries of `failedSmartPlusAds`."}}},"oldestReadAt":{"type":["string","null"],"format":"date-time","description":"The oldest `readAt` in `items`. Null when `items` is empty."},"items":{"type":"array","items":{"type":"object","properties":{"smartPlusAdId":{"type":"string"},"adGroupId":{"type":["string","null"]},"campaignId":{"type":["string","null"]},"review":{"$ref":"#/components/schemas/TikTokSmartPlusAdLevelReview"},"materials":{"type":"array","description":"One entry per creative TikTok reviewed (`material_review_infos`).","items":{"$ref":"#/components/schemas/TikTokSmartPlusMaterialReview"}},"readAt":{"type":"string","format":"date-time","description":"When the verdict was read from TikTok, kept as is when served from the store. Older than `maxAgeSeconds` means stale."}}}},"failedSmartPlusAds":{"type":"array","description":"Smart+ ads of this page whose review TikTok refused on its own (e.g. an ad deleted on TikTok since the listing was read). Empty when none.\n\nZernio splits a refused batch in halves (at most 16 extra calls per page), so the batch's other ads are still read. Ads left unresolved by that cap stay in `items` with their stored review, or in `pendingSmartPlusAdIds`.\n","items":{"type":"object","properties":{"smartPlusAdId":{"type":"string"},"adGroupId":{"type":["string","null"]},"campaignId":{"type":["string","null"]},"error":{"type":"object","properties":{"tiktokCode":{"type":["integer","null"],"description":"TikTok's error code, verbatim."},"message":{"type":"string","description":"TikTok's error message, verbatim."}}},"refusedAt":{"type":["string","null"],"format":"date-time","description":"When TikTok refused this ad. Null for a refusal stored before this field existed."}}}},"incomplete":{"type":"boolean","description":"True while some Smart+ ads of this page were never read (`counts.pending > 0`). Stale items alone keep it false."},"allFresh":{"type":"boolean","description":"True when every item and refusal of this page was read within `maxAgeSeconds` and nothing is pending. False with `incomplete: false` means the page is complete but some reviews are older than the window; a later read refreshes them oldest first."},"pendingSmartPlusAdIds":{"type":"array","items":{"type":"string"},"description":"Smart+ ads of this page never read. Empty when every ad has a stored review or refusal."},"retryAfterSeconds":{"type":["integer","null"],"description":"Seconds until Zernio calls TikTok's review endpoint for this advertiser and connection again (the stored pause with its jitter). Set exactly when `refreshState` is `paused` or `refused`, including stale items with nothing pending. Always equals the `Retry-After` header, which is sent exactly when this is not null.\n\nClient rule:\n\n- Present: wait that long before reading the page again.\n- null with stale or pending ads: a retry is not blocked. Read again now or on your `maxAgeSeconds` schedule; with `refreshState: error`, check `reviewError` first."},"refreshState":{"type":"string","enum":["ok","paused","refused","error"],"description":"Whether this request could refresh the due (stale or pending) Smart+ ads of the page.\n\n- `refused`: TikTok refused a review call of this request over quota (40002 `OVER_QPS_LIMIT` or 40100) and Zernio paused. Carries `retryAfterSeconds`.\n- `paused`: no call was sent for the due ads, because a pause from an earlier refusal is still running or another request is refreshing the same advertiser (then `retryAfterSeconds` is 20). Carries `retryAfterSeconds`.\n- `error`: TikTok refused the batch for another reason (both halves the same way). The page is served from stored reviews and `reviewError` holds TikTok's error. `retryAfterSeconds` is null because retrying soon repeats the refusal.\n- `ok`: nothing blocks a retry. Every due ad was read, none was due, or the split cap or the 20-second request budget left some for the next read, which can come right away."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"accountId is not a TikTok or TikTok Ads connection (code feature_not_available)."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"description":"The TikTok connection has no TikTok Ads token: connect TikTok Ads first (code ads_connection_required)."},"429":{"description":"TikTok's general rate limit hit while listing the Smart+ ads (`Retry-After: 10`).","$ref":"#/components/responses/RateLimited"}}}},"/v1/ads/instagram-accounts":{"get":{"x-resource-group":"ads","operationId":"listAdsInstagramAccounts","summary":"List Instagram ad identities","description":"Lists the Instagram accounts a Meta ad connection can run ads as, so you can pick the identity for a new ad.\n\nDiscovers identities through connected_instagram_accounts, Page linkage and Page-backed identities, with a best-effort business fallback. Business permission errors do not fail discovery. The resolved object uses the same profile-scoped resolver as ad creation; null means no identity was resolved. Format-specific observed-actor fallbacks at creative creation are not predicted.\n","tags":["Ad Accounts"],"x-platforms":["meta"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio Meta Ads or Facebook SocialAccount ID."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string","pattern":"^act_[0-9]+$"},"description":"Meta ad account ID including the act_ prefix."}],"responses":{"200":{"description":"Instagram identities and Page linkage.","content":{"application/json":{"schema":{"type":"object","required":["accounts","pages","resolved"],"properties":{"accounts":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/MetaInstagramIdentityRef"},{"type":"object","required":["isPageBacked","source"],"properties":{"isPageBacked":{"type":"boolean","description":"Whether this is a Page-backed Instagram identity."},"source":{"type":"string","enum":["ad_account","page_backed","business"],"description":"Discovery source; Page linkage also uses page_backed."}}}]}},"pages":{"type":"array","items":{"type":"object","required":["pageId","name"],"properties":{"pageId":{"type":"string","description":"Facebook Page ID."},"name":{"type":"string","description":"Facebook Page name."},"instagramBusinessAccount":{"$ref":"#/components/schemas/MetaInstagramIdentityRef"},"connectedInstagramAccount":{"$ref":"#/components/schemas/MetaInstagramIdentityRef"}}}},"resolved":{"type":"object","required":["pageId","igUserId","source"],"properties":{"pageId":{"type":["string","null"],"description":"Page selected by the shared ad-creation resolver."},"igUserId":{"type":["string","null"],"description":"Instagram identity selected by the shared ad-creation resolver."},"source":{"type":["string","null"],"enum":["ad_account","page_backed","business",null],"description":"Discovery source of the resolved identity; null when absent from discovery."}}}}},"example":{"accounts":[{"igUserId":"17841400000000000","username":"example","isPageBacked":false,"source":"page_backed"}],"pages":[{"pageId":"123456789","name":"Example Page","instagramBusinessAccount":{"igUserId":"17841400000000000","username":"example"}}],"resolved":{"pageId":"123456789","igUserId":"17841400000000000","source":"page_backed"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The account or Meta asset is not accessible."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta Ads and Facebook accounts."}}}},"/v1/ads/instagram-posts":{"get":{"x-resource-group":"ads","operationId":"listAdsInstagramPosts","summary":"List Instagram posts to boost","description":"Lists posts from the Instagram account a Meta ad connection can reach, so you can boost one as an ad.\n\nAn existing Instagram post can be boosted this way without connecting the Instagram account separately. Each `posts[].id` is the existing-post id to send as `platformPostId` when creating the ad; Meta turns it into `source_instagram_media_id` on the creative.\n\nIdentity resolution reuses the same resolver as `/v1/ads/instagram-accounts`. `igUserId` is always checked against the identities the connection can reach and is never trusted as sent.\n\n### When no identity is reachable\n\nThe endpoint fails instead of returning an empty list, and the two causes stay apart:\n\n- `403 reconnect_required`: the connection predates Instagram access, and the account must be reconnected granting Instagram access. Meta then omits `instagram_business_account` from the Page read rather than erroring, so it looks identical to having no data.\n- `422 instagram_business_account_unresolved`: the Page genuinely has no Instagram professional account linked.\n","tags":["Ad Accounts"],"x-platforms":["meta"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio Meta Ads, Facebook or Instagram SocialAccount ID."},{"name":"adAccountId","in":"query","required":false,"schema":{"type":"string","pattern":"^act_[0-9]+$"},"description":"Meta ad account ID including the act_ prefix. Narrows identity resolution to the Instagram accounts reachable from this ad account."},{"name":"igUserId","in":"query","required":false,"schema":{"type":"string"},"description":"Instagram identity to list. Must be one this connection can reach, otherwise the request is rejected with a 400."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Number of posts to return per page."},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque Meta cursor from a previous response's paging.after."}],"responses":{"200":{"description":"Instagram posts available to boost.","content":{"application/json":{"schema":{"type":"object","required":["igUserId","username","posts","paging"],"properties":{"igUserId":{"type":"string","description":"Instagram identity the posts belong to."},"username":{"type":"string","description":"Instagram username; empty when Meta does not expose it."},"posts":{"type":"array","items":{"type":"object","required":["id","mediaType","timestamp"],"properties":{"id":{"type":"string","description":"Instagram media ID. Pass this as the existing-post id when creating an ad."},"caption":{"type":"string","description":"Caption, when the media has one."},"mediaType":{"type":"string","description":"Meta media_type, e.g. IMAGE, VIDEO or CAROUSEL_ALBUM."},"mediaUrl":{"type":"string","description":"Media URL. Meta omits it for some media types."},"thumbnailUrl":{"type":"string","description":"Thumbnail URL. Present for VIDEO, where mediaUrl may be absent."},"permalink":{"type":"string","description":"Public Instagram permalink."},"timestamp":{"type":"string","description":"Publish time as Meta reports it."}}}},"paging":{"type":"object","required":["after"],"properties":{"after":{"type":["string","null"],"description":"Cursor for the next page, or null when this is the last one."}}}}},"example":{"igUserId":"17841400000000000","username":"example","posts":[{"id":"18050809559368305","caption":"Launch day","mediaType":"VIDEO","thumbnailUrl":"https://scontent.cdninstagram.com/thumb.jpg","permalink":"https://www.instagram.com/reel/ABCdef/","timestamp":"2026-09-18T09:00:00+0000"}],"paging":{"after":"QVFIUl..."}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The connection predates Instagram access (code reconnect_required) and must be reconnected, or the Meta asset is not accessible."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"x-summary":"The Facebook Page has no linked Instagram professional account, or no Page is selected: link one or pass `adAccountId`.","description":"The Facebook Page has no linked Instagram professional account (code instagram_business_account_unresolved), or the connection has no Page selected and no adAccountId was passed (code linked_account_required)."},"501":{"description":"Only supported on Meta Ads, Facebook and Instagram accounts."}}}},"/v1/ads/advertisable-applications":{"get":{"x-resource-group":"ads","operationId":"listAdvertisableApplications","summary":"List advertisable apps","description":"Lists the mobile apps a Meta ad account can promote, with their platforms and store links, for app install campaigns.\n\nLists applications available to a Meta ad account, their supported platforms and unmodified object store URLs. A listed app still needs a configured mobile platform and store URL to run install promotion.\n","tags":["Ad Accounts"],"x-platforms":["meta"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio Meta Ads or Facebook SocialAccount ID."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string","pattern":"^act_[0-9]+$"},"description":"Meta ad account ID including the act_ prefix."}],"responses":{"200":{"description":"Applications available for promotion.","content":{"application/json":{"schema":{"type":"object","required":["applications"],"properties":{"applications":{"type":"array","items":{"type":"object","required":["id","name","supportedPlatforms","storeUrls"],"properties":{"id":{"type":"string","description":"Meta application ID."},"name":{"type":"string","description":"Application name."},"supportedPlatforms":{"type":"array","items":{"type":"string"},"description":"Platform identifiers reported by Meta."},"storeUrls":{"type":"object","additionalProperties":{"type":"string"},"description":"Platform-keyed store URLs returned unchanged by Meta."}}}}}},"example":{"applications":[{"id":"123456789","name":"Example App","supportedPlatforms":["IOS","ANDROID"],"storeUrls":{"iphone":"https://apps.apple.com/app/id123456789","google_play":"https://play.google.com/store/apps/details?id=com.example.app"}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The account or Meta asset is not accessible, or the ad account is not selected: add the account to the selection.","description":"The account or Meta asset is not accessible.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix it, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta Ads and Facebook accounts."}}}},"/v1/ads/ios-fourteen-campaign-limits":{"get":{"x-resource-group":"ads","operationId":"getIosFourteenCampaignLimits","summary":"Get iOS 14 campaign limits","description":"Shows Meta's iOS 14 campaign limits for an app on an ad account (it does not confirm the app is set up for iOS promotion).\n\napplicationId is sent as Meta app_id. This read does not establish that the application is configured for iOS promotion.\n","tags":["Ad Accounts"],"x-platforms":["meta"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio Meta Ads or Facebook SocialAccount ID."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string","pattern":"^act_[0-9]+$"},"description":"Meta ad account ID including the act_ prefix."},{"name":"applicationId","in":"query","required":true,"schema":{"type":"string","pattern":"^[0-9]+$"},"description":"Meta application ID from advertisable-applications."}],"responses":{"200":{"description":"Application campaign limits.","content":{"application/json":{"schema":{"type":"object","required":["limits"],"properties":{"limits":{"type":["object","null"],"properties":{"campaignGroupLimit":{"type":["number","null"],"description":"Campaign group limit reported by Meta."},"campaignLimit":{"type":["number","null"],"description":"Campaign limit reported by Meta."},"campaignGroupLimitsDetails":{"type":"array","items":{},"description":"Campaign group limit details returned by Meta."}}}}},"example":{"limits":{"campaignGroupLimit":9,"campaignLimit":5,"campaignGroupLimitsDetails":[]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The account or Meta asset is not accessible, or the ad account is not selected: add the account to the selection.","description":"The account or Meta asset is not accessible.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta Ads and Facebook accounts."}}}},"/v1/ads/businesses":{"get":{"x-resource-group":"ads","operationId":"listMetaBusinesses","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"Businesses list","description":"Lists the Meta business portfolios the connected user belongs to, with their verification status.\n\nBusiness Manager portfolios the connected Meta user belongs to (Meta's `/me/businesses`),\nrows returned verbatim (id, name, verification_status, created_time). Token-scoped, so no\n`adAccountId` is needed. For TikTok Business Centers use\n`GET /v1/ads/business-centers`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Rows per page"},{"name":"after","in":"query","schema":{"type":"string"},"description":"Cursor from paging.after of the previous page."}],"responses":{"200":{"description":"Businesses (raw Meta shape)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"Raw Meta business row (id, name, verification_status, created_time)."}},"paging":{"type":"object","properties":{"after":{"type":["string","null"],"description":"Cursor for the next page; null when exhausted."}}}}}}}},"400":{"description":"Invalid input, or Meta rejected the query"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/businesses/users":{"get":{"x-resource-group":"ads","operationId":"listMetaBusinessUsers","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"Business users","description":"Lists the people and system users of a Meta business portfolio, with the ids you need to assign them to Pages or ad accounts.\n\nPeople and system users of a Meta business portfolio, with the business-scoped ids that\n`POST /v1/ads/accounts/users` and `POST /v1/ads/page-users` take. The connected Meta\nuser must be an admin of the portfolio.","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."},{"name":"businessId","in":"query","required":true,"schema":{"type":"string"},"description":"Meta business portfolio id."}],"responses":{"200":{"description":"Business users","content":{"application/json":{"schema":{"type":"object","properties":{"businessId":{"type":"string"},"users":{"type":"array","items":{"$ref":"#/components/schemas/MetaBusinessUser"}},"systemUsers":{"type":"array","items":{"$ref":"#/components/schemas/MetaBusinessUser"}}}}}}},"400":{"description":"Invalid input, or Meta rejected the query"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Meta refused: the token lacks business_management or business admin access."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/page-users":{"get":{"x-resource-group":"ads","operationId":"listPageUsers","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"Page users of a business","description":"Lists the people in a business portfolio who are assigned to a Facebook Page it owns or was shared as a partner.\n\nPeople of a business portfolio assigned to a Facebook Page the portfolio owns or was\ngranted as a partner (`POST /v1/accounts/{accountId}/business-partners` on the owner side).","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."},{"name":"pageId","in":"query","required":true,"schema":{"type":"string"},"description":"Facebook Page id."},{"name":"businessId","in":"query","required":true,"schema":{"type":"string"},"description":"Business portfolio whose people to list."}],"responses":{"200":{"description":"Assigned users","content":{"application/json":{"schema":{"type":"object","properties":{"pageId":{"type":"string"},"businessId":{"type":"string"},"users":{"type":"array","items":{"$ref":"#/components/schemas/MetaAssignedUser"}}}}}}},"400":{"description":"Invalid input, or Meta rejected the query"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Meta refused: the token lacks business_management or business admin access."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}},"post":{"x-resource-group":"ads","operationId":"assignPageUser","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"Assign a user to a Page","description":"Gives a person in your business portfolio tasks on a Facebook Page, such as advertising, so they can run ads for it.\n\nThe Page can be one the portfolio owns or was granted as a partner. Meta does not assign partner admins automatically, so after an owner shares a Page the partner calls this for the people whose tokens will advertise for it.\n\n- `ADVERTISE` is what ad creation needs.\n- Assigning an already assigned user replaces their task set.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","pageId","businessId","userId","tasks"],"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id used to resolve the Meta token."},"pageId":{"type":"string","description":"Facebook Page id."},"businessId":{"type":"string","description":"Business portfolio the user belongs to."},"userId":{"type":"string","description":"Business-scoped user id from GET /v1/ads/businesses/users."},"tasks":{"type":"array","minItems":1,"items":{"type":"string","enum":["MANAGE","CREATE_CONTENT","MODERATE","MESSAGING","ADVERTISE","ANALYZE"]}}}},"example":{"accountId":"64b1f0c8a1b2c3d4e5f60718","pageId":"123456789012345","businessId":"1234567890123","userId":"1122334455","tasks":["ADVERTISE","ANALYZE"]}}}},"responses":{"201":{"description":"User assigned","content":{"application/json":{"schema":{"type":"object","properties":{"pageId":{"type":"string"},"businessId":{"type":"string"},"user":{"type":"object","properties":{"id":{"type":"string"},"tasks":{"type":"array","items":{"type":"string"}}}}}}}}},"400":{"description":"Invalid input, or Meta rejected the request"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Meta refused: the token lacks business_management or business admin access."},"404":{"description":"Account not found, or Meta could not load the user or Page."},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}},"delete":{"x-resource-group":"ads","operationId":"removePageUser","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"Remove a user from a Page","description":"Removes a person's access to a Facebook Page assigned through your business portfolio.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id used to resolve the Meta token."},{"name":"pageId","in":"query","required":true,"schema":{"type":"string"},"description":"Facebook Page id."},{"name":"userId","in":"query","required":true,"schema":{"type":"string"},"description":"Business-scoped user id."}],"responses":{"200":{"description":"User removed","content":{"application/json":{"schema":{"type":"object","properties":{"pageId":{"type":"string"},"userId":{"type":"string"},"removed":{"type":"boolean"}}}}}},"400":{"description":"Invalid input, or Meta rejected the request"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Meta refused: the token lacks business_management or business admin access."},"404":{"description":"Account not found, or Meta could not load the user or Page."},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/labels":{"get":{"x-resource-group":"ads","operationId":"listAdLabels","tags":["Ad Accounts"],"x-platforms":["meta","google"],"summary":"List ad labels","description":"Lists the labels used to organise campaigns and ads in an ad account.\n\n### Meta\n\nPass `adAccountId=act_<n>`. Rows are Meta's `/act_X/adlabels` returned verbatim (id, name, created/updated time), paginated with `limit` / `after`.\n\n### Google Ads\n\nPass the numeric customer id as `adAccountId` (optional when the connection has a single customer).\n\n- Returns every non-removed label as a `GoogleAdLabel` in one page (`paging.after` is always null).\n- Reads are cached for 10 minutes.\n- When the shared Google quota is exhausted, the last successful result is served with `stale: true`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id. For Meta, the posting or ads variant used to resolve the token."},{"name":"adAccountId","in":"query","schema":{"type":"string","pattern":"^(act_)?\\d+$"},"description":"Meta ad account id (act_<n>), or the Google Ads customer id (digits only)."},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Google only. Alias of adAccountId, kept for existing callers."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Meta only. Rows per page."},{"name":"after","in":"query","schema":{"type":"string"},"description":"Meta only. Cursor from paging.after of the previous page."}],"responses":{"200":{"description":"Ad labels","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string","description":"Meta act_<n>, or the resolved Google customer id"},"data":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/GoogleAdLabel"},{"type":"object","description":"Raw Meta ad label row (id, name, created_time, updated_time)."}]}},"paging":{"type":"object","properties":{"after":{"type":["string","null"],"description":"Cursor for the next page; null when exhausted (always null on Google)."}}},"cachedAt":{"type":["string","null"],"format":"date-time","description":"Google only. When the served list was fetched from Google."},"stale":{"type":"boolean","description":"Google only. True when Google quota was exhausted and the last cached list was served."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta and Google Ads accounts"}}},"post":{"x-resource-group":"ads","operationId":"createAdLabel","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"Create a Google Ads label","description":"Creates a Google Ads label you can then attach to campaigns, ad groups, ads and keywords to organize and filter them.\n\nAttach it to campaigns, ad groups, ads and\nkeywords with `POST /v1/ads/labels/{labelId}/assignments`. Label names are unique per\ncustomer; a duplicate is a 400.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["accountId","name"],"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id (Google Ads)"},"adAccountId":{"type":"string","pattern":"^\\d+$","description":"Google customer id. Required when the connection has multiple customers."},"customerId":{"type":"string","pattern":"^\\d+$","deprecated":true,"description":"Alias of adAccountId"},"name":{"type":"string","minLength":1,"maxLength":80,"description":"Trimmed before sending."},"backgroundColor":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","description":"#RRGGBB. Google picks a color when omitted."},"description":{"type":"string","maxLength":200}}}}}},"responses":{"201":{"description":"Label created","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"id":{"type":"string","description":"Google label id"},"resourceName":{"type":"string","description":"customers/{customerId}/labels/{id}"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only available on Google Ads accounts"}}}},"/v1/ads/labels/{labelId}":{"patch":{"x-resource-group":"ads","operationId":"updateAdLabel","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"Update a Google Ads label","description":"Changes a Google Ads label's name, color or description.\n\nOnly the fields sent are written.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"labelId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Google label id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["accountId"],"minProperties":2,"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id (Google Ads)"},"adAccountId":{"type":"string","pattern":"^\\d+$","description":"Google customer id. Required when the connection has multiple customers."},"customerId":{"type":"string","pattern":"^\\d+$","deprecated":true,"description":"Alias of adAccountId"},"name":{"type":"string","minLength":1,"maxLength":80},"backgroundColor":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"description":{"type":"string","maxLength":200,"description":"Send \"\" to clear it."}}}}}},"responses":{"200":{"description":"Label updated","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"label":{"$ref":"#/components/schemas/GoogleAdLabel"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"description":"Label not found on this customer, or account unavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only available on Google Ads accounts"}}},"delete":{"x-resource-group":"ads","operationId":"removeAdLabel","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"Remove a Google Ads label","description":"Deletes a Google Ads label and removes it from everything it was attached to.\n\nGoogle drops it from every campaign, ad group, ad and keyword it was attached to.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"labelId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Google label id"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (Google Ads)"},{"name":"adAccountId","in":"query","schema":{"type":"string","pattern":"^\\d+$"},"description":"Google customer id. Required when the connection has multiple customers."},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Alias of adAccountId"}],"responses":{"200":{"description":"Label removed","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"labelId":{"type":"string"},"removed":{"type":"boolean","description":"Always true on success"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"description":"Label not found on this customer, or account unavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only available on Google Ads accounts"}}}},"/v1/ads/labels/{labelId}/assignments":{"post":{"x-resource-group":"ads","operationId":"attachAdLabel","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"Attach a Google Ads label","description":"Attaches a Google Ads label to campaigns, ad groups, ads and keywords in one call, skipping any that already have it.\n\nThe label goes to campaigns, ad groups, ads and keywords (Google CampaignLabel, AdGroupLabel, AdGroupAdLabel and AdGroupCriterionLabel) in one mutate.\n\nIdempotent: a target that already carries the label is counted in `unchanged` instead of failing the call.\n\n### Ids\n\nAll ids are Google's own. Ads and keywords use the composite id Google puts in their resource names:\n\n- Ads: `{adGroupId}~{adId}`\n- Keywords: `{adGroupId}~{criterionId}` (the tail of `resourceName` on `GET /v1/ads/keywords`)\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"labelId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Google label id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleAdLabelAssignments"}}}},"responses":{"200":{"description":"Label attached","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"labelId":{"type":"string"},"attached":{"type":"integer","description":"Links created by this call"},"unchanged":{"type":"integer","description":"Targets that already carried the label"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"description":"Label not found on this customer, or account unavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only available on Google Ads accounts"}}},"delete":{"x-resource-group":"ads","operationId":"detachAdLabel","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"Detach a Google Ads label","description":"Removes a Google Ads label from the campaigns, ad groups, ads or keywords you name, skipping any that do not have it.\n\nIdempotent; a target without the label is counted in `unchanged`. Fields go in the query string. A JSON body with the same fields is also accepted and, when sent, the query string is ignored.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"labelId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Google label id"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"description":"Zernio Google Ads connection id."},{"name":"adAccountId","in":"query","schema":{"type":"string","pattern":"^\\d+$"},"description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Alias of adAccountId, kept for existing callers"},{"name":"campaignIds","in":"query","style":"form","explode":true,"schema":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"string","pattern":"^\\d+$"}},"description":"Google campaign ids. Repeat the parameter or pass a comma-separated list."},{"name":"adSetIds","in":"query","style":"form","explode":true,"schema":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"string","pattern":"^\\d+$"}},"description":"Google ad group ids. Repeat the parameter or pass a comma-separated list."},{"name":"adIds","in":"query","style":"form","explode":true,"schema":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"string","pattern":"^\\d+~\\d+$"}},"description":"Google ad group ad ids, {adGroupId}~{adId}. Repeat the parameter or pass a comma-separated list."},{"name":"keywordIds","in":"query","style":"form","explode":true,"schema":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"string","pattern":"^\\d+~\\d+$"}},"description":"Google keyword criterion ids, {adGroupId}~{criterionId}. Repeat the parameter or pass a comma-separated list."}],"responses":{"200":{"description":"Label detached","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"labelId":{"type":"string"},"detached":{"type":"integer","description":"Links removed by this call"},"unchanged":{"type":"integer","description":"Targets that did not carry the label"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"description":"Label not found on this customer, or account unavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only available on Google Ads accounts"}}}},"/v1/ads/high-demand-periods":{"get":{"x-resource-group":"ads","operationId":"listHighDemandPeriods","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"List high-demand periods","description":"Lists the scheduled budget increases set on a Meta campaign or ad set.\n\nScheduled budget increases (Meta's budget-scheduling API). The Graph edge lives on the\ncampaign and ad-set nodes only, so exactly one of `campaignId` / `adSetId` (platform\nids) is required. Rows returned verbatim (budget_value, budget_value_type, time window,\nrecurrence).","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."},{"name":"campaignId","in":"query","schema":{"type":"string"},"description":"Platform campaign id. Exactly one of campaignId / adSetId."},{"name":"adSetId","in":"query","schema":{"type":"string"},"description":"Platform ad set id. Exactly one of campaignId / adSetId."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Rows per page"},{"name":"after","in":"query","schema":{"type":"string"},"description":"Cursor from paging.after of the previous page."}],"responses":{"200":{"description":"Budget schedules (raw Meta shape)","content":{"application/json":{"schema":{"type":"object","properties":{"objectId":{"type":"string","description":"The campaign / ad set id the schedules belong to."},"data":{"type":"array","items":{"type":"object","description":"Raw Meta high-demand-period row."}},"paging":{"type":"object","properties":{"after":{"type":["string","null"],"description":"Cursor for the next page; null when exhausted."}}}}}}}},"400":{"description":"Invalid input, or Meta rejected the query"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}},"post":{"x-resource-group":"ads","operationId":"createHighDemandPeriod","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"Schedule a budget increase","description":"Schedules a temporary budget increase on a Meta campaign or ad set for a busy period, like Black Friday or a launch.\n\nSame target rule as the GET: exactly one of `campaignId` / `adSetId`.\n\n### Meta constraints\n\n- `timeStart` / `timeEnd` must fall on a 15-minute boundary.\n- A campaign cannot mix `ABSOLUTE` and `MULTIPLIER` across its schedules. The second type is rejected with \"Can't mix your budget scaling selection\".\n- Window rules (must sit inside the campaign's run dates, minimum lead time, no overlap) are Meta's, and its message is forwarded verbatim.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","budgetValue","budgetValueType","timeStart","timeEnd"],"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id used to resolve the Meta token."},"campaignId":{"type":"string","description":"Platform campaign id. Exactly one of campaignId / adSetId."},"adSetId":{"type":"string","description":"Platform ad set id. Exactly one of campaignId / adSetId."},"budgetValue":{"type":"number","description":"With ABSOLUTE, a budget in the ad account's currency in WHOLE units (50 = $50.00). With MULTIPLIER, a factor of the existing budget (2 = double it) and NOT a currency amount."},"budgetValueType":{"type":"string","enum":["ABSOLUTE","MULTIPLIER"]},"timeStart":{"type":"integer","description":"Unix seconds, on a 15-minute boundary (:00, :15, :30, :45)."},"timeEnd":{"type":"integer","description":"Unix seconds, on a 15-minute boundary and after timeStart."},"recurrenceType":{"type":"string","enum":["ONE_TIME","WEEKLY","MONTHLY"]},"currency":{"type":"string","description":"Ad account currency, for the ABSOLUTE minor-unit conversion. Ignored for MULTIPLIER."}}}}}},"responses":{"201":{"description":"Budget schedule created","content":{"application/json":{"schema":{"type":"object","properties":{"objectId":{"type":"string","description":"The campaign / ad set the schedule was attached to."},"id":{"type":"string","description":"Meta budget schedule id."}}}}}},"400":{"description":"Invalid input, or Meta rejected the schedule"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/creatives":{"get":{"x-resource-group":"ads","operationId":"listAdCreatives","tags":["Ad Creatives"],"x-platforms":["meta"],"summary":"Creative library","description":"Lists the creatives saved in a Meta ad account so you can reuse one in a new ad.\n\nLists the ad account's creative library (Meta's `/act_X/adcreatives`), rows returned\nverbatim. The default projection covers id, name, status, object type, thumbnail,\nobject_story_spec / asset_feed_spec and url_tags; `fields` is a raw-passthrough\noverride. Any creative id here is reusable on the create endpoints via\n`existingCreativeId`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"Meta ad account id (act_<n>)."},{"name":"fields","in":"query","schema":{"type":"string","example":"id,name,status,object_story_spec{page_id,link_data{link,message}}"},"description":"Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers, so a nested edge can be paged explicitly: without a .limit() modifier the expansion runs at the Meta default page size and the tail is dropped silently."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Rows per page"},{"name":"after","in":"query","schema":{"type":"string"},"description":"Cursor from paging.after of the previous page."}],"responses":{"200":{"description":"Creatives (raw Meta shape)","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"data":{"type":"array","items":{"type":"object","description":"Raw Meta creative row."}},"paging":{"type":"object","properties":{"after":{"type":["string","null"],"description":"Cursor for the next page; null when exhausted."}}}}}}}},"400":{"description":"Invalid input, or Meta rejected the query"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}},"post":{"x-resource-group":"ads","operationId":"createAdCreative","tags":["Ad Creatives"],"x-platforms":["meta"],"summary":"Create a standalone creative","description":"Creates a reusable Meta creative from an image or carousel without creating an ad, ready to attach to ads later.\n\nThe creative goes in the library WITHOUT an ad, reusable on the create endpoints via `existingCreativeId`.\n\n### Source\n\nProvide exactly one of:\n\n- `imageUrl` (uploaded server-side)\n- `imageHash` (from POST /v1/ads/images or the library list)\n- `carouselCards` (2-10 hand-built cards)\n\n### Other fields\n\n- The Page (and linked Instagram account, when present) is resolved from `accountId` as the story actor. `instagramAccountId` overrides the Instagram account.\n- `creativeFeatures` configures Advantage+ enhancements.\n- `promotion` is not supported and any object is rejected with 400.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","adAccountId","headline","body","linkUrl"],"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token and Page."},"adAccountId":{"type":"string","description":"Platform ad account id (Meta act_<n>, Google customer id, LinkedIn account id, ...)."},"headline":{"type":"string","maxLength":255},"body":{"type":"string","description":"Primary text"},"description":{"type":"string","maxLength":255,"description":"Link description below the headline; omitted = Meta scrapes the destination's OG description."},"callToAction":{"type":"string","default":"LEARN_MORE","description":"CTA type (same whitelist as POST /v1/ads/create)."},"linkUrl":{"type":"string","format":"uri"},"imageUrl":{"type":"string","format":"uri","description":"Publicly reachable image; uploaded to the account's library server-side."},"imageHash":{"type":"string","description":"Existing library image hash (POST /v1/ads/images or GET /v1/ads/images)."},"carouselCards":{"type":"array","minItems":2,"maxItems":10,"items":{"type":"object","required":["imageUrl","linkUrl"],"properties":{"imageUrl":{"type":"string","format":"uri"},"linkUrl":{"type":"string","format":"uri"},"headline":{"type":"string","maxLength":255},"description":{"type":"string","maxLength":255},"callToAction":{"type":"string"}}}},"instagramAccountId":{"type":"string","minLength":1,"description":"Meta only. The Instagram account the creative runs as, mapped to `instagram_user_id`: an id from `GET /v1/ads/instagram-accounts`, including a Page-backed one.\n\n- Given, it is never swapped. One the ad account cannot use returns 400 `insufficient_permissions` on `instagramAccountId`.\n- Omitted, it uses the account linked to the Page. When the ad account has no access to that one, it retries once with an authorized Instagram account, or returns 422 on `instagramAccountId` when there is none.\n"},"optimizeCardOrder":{"type":"boolean","description":"Only with `carouselCards` (a 400 without them). Sets `link_data.multi_share_optimized`:\n\n- `false`: keeps the cards in the order given. Meta then takes at most 5 cards, so `false` with more than 5 cards is a 400.\n- `true`: lets Meta reorder them for performance.\n- Omitted: nothing is sent and Meta's default (`true`) applies.\n"},"urlTags":{"type":"string","description":"Appended to every outbound URL (e.g. utm_source=fb)."},"promotion":{"$ref":"#/components/schemas/MetaPromotion","description":"Not supported. Any object is rejected with 400 invalid_field_value. Send null or omit the field, and set the Promotion on the ad in Ads Manager.\n\nMeta validates creative_sourcing_spec.promotion_metadata_spec on the create call and then discards it, so a Promotion set through the Marketing API never reaches the creative. Verified on 2026-09-11 across Graph v19.0 to v25.0 and every write path.\n"},"creativeFeatures":{"$ref":"#/components/schemas/MetaCreativeFeatures","description":"Meta only. Applied to each new creative, including standalone and attach shapes. With creatives[], these are defaults; an item replaces the whole feature map, including an empty map. auto_promotion_tag is an Advantage+ enhancement, not the Ads Manager Promotion setting."},"multiAdvertiser":{"type":"string","enum":["OPT_IN","OPT_OUT"],"description":"Meta only. Multi-advertiser ads: whether Meta may show this ad alongside other advertisers' in one unit. Meta auto-enrols since Aug 2024, so send OPT_OUT to leave. It is a top-level creative field, NOT a `creativeFeatures` key, and Meta rejects it there."},"aiDisclosure":{"type":"string","enum":["OPT_IN","OPT_OUT"],"description":"Meta only. Meta's \"Ad includes media created or edited with AI\" disclosure (the Ads Manager checkbox), stored on the creative as `generative_asset_spec.transparency_metadata.self_disclosure`.\n\n- OPT_IN: checks it.\n- OPT_OUT: explicitly declares no AI media.\n- Omitted: leaves Meta's default.\n\nApplied to each new creative (standalone, creatives[] and attach shapes) and preserved when a creative is rebuilt. This sets the disclosure on the ad; whether and when the viewer-facing label renders is Meta's decision.\n"}}},"example":{"accountId":"69fc524892b3d8e85f893e73","adAccountId":"act_123456789","headline":"Save on your next order","body":"Use SAVE20 at checkout.","linkUrl":"https://example.com/shop","imageUrl":"https://example.com/ad.jpg","creativeFeatures":{"auto_promotion_tag":"OPT_OUT"}}}}},"responses":{"201":{"description":"Creative created","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"creativeId":{"type":"string","description":"Platform creative id, reusable via existingCreativeId."}}},"example":{"adAccountId":"act_123456789","creativeId":"123456789012345"}}}},"400":{"description":"Invalid input, or Meta rejected the create"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"description":"No Facebook Page found to act as the story actor"},"501":{"description":"Only supported on Meta (facebook/instagram)"},"502":{"x-summary":"Meta accepted the request but failed to produce the image, for example from an upload or processing timeout.","description":"Meta accepted the request then failed to produce the media (upload session, chunk transfer, processing timeout, or a response with no image hash). Inspect `platformError.reason`."}}}},"/v1/ads/creatives/{creativeId}":{"get":{"x-resource-group":"ads","operationId":"getAdCreative","tags":["Ad Creatives"],"x-platforms":["meta"],"summary":"Creative details","description":"Shows the details of one Meta creative, such as its content, status and thumbnail.\n\nOne creative's details, verbatim from Meta. `fields` is a raw-passthrough override of\nthe default projection.","security":[{"bearerAuth":[]}],"parameters":[{"name":"creativeId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform creative id"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."},{"name":"fields","in":"query","schema":{"type":"string","example":"id,name,status,object_story_spec{page_id,link_data{link,message}}"},"description":"Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers, so a nested edge can be paged explicitly: without a .limit() modifier the expansion runs at the Meta default page size and the tail is dropped silently."},{"name":"thumbnailWidth","in":"query","schema":{"type":"integer","minimum":1,"maximum":4096,"example":600},"description":"Width in pixels of the `thumbnail_url` rendering, forwarded to Meta as `thumbnail_width`. Without it Meta returns a 64x64 thumbnail."},{"name":"thumbnailHeight","in":"query","schema":{"type":"integer","minimum":1,"maximum":4096,"example":600},"description":"Height in pixels of the `thumbnail_url` rendering, forwarded to Meta as `thumbnail_height`. Without it Meta returns a 64x64 thumbnail."}],"responses":{"200":{"description":"Creative details","content":{"application/json":{"schema":{"type":"object","properties":{"creative":{"type":"object","description":"Raw Meta creative node"}}}}}},"400":{"description":"Invalid input, or Meta rejected the query"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}},"put":{"x-resource-group":"ads","operationId":"updateAdCreative","tags":["Ad Creatives"],"x-platforms":["meta"],"summary":"Rename a creative","description":"Renames a Meta creative (Meta does not allow other changes, so make a new creative to change its content).\n\nCreatives are immutable on Meta beyond `name`. For content changes\ncreate a new creative (POST /v1/ads/creatives) and swap it onto the ad\n(PUT /v1/ads/{adId} with `creative`).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"creativeId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform creative id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","name"],"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id (posting or ads variant); its platform decides where the campaign is created."},"name":{"type":"string","maxLength":255}}}}}},"responses":{"200":{"description":"Creative renamed","content":{"application/json":{"schema":{"type":"object","properties":{"creativeId":{"type":"string"},"name":{"type":"string"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid input, or Meta rejected the update"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}},"delete":{"x-resource-group":"ads","operationId":"deleteAdCreative","tags":["Ad Creatives"],"x-platforms":["meta"],"summary":"Delete a creative","description":"Deletes a Meta creative from the library, which Meta only allows when no ad uses it.\n\nMeta only allows deleting creatives not referenced\nby any ad; otherwise its 400 surfaces verbatim.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"creativeId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform creative id"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."}],"responses":{"200":{"description":"Creative deleted","content":{"application/json":{"schema":{"type":"object","properties":{"creativeId":{"type":"string"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid input, the creative is in use, or Meta rejected the delete"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/value-rule-sets":{"get":{"x-resource-group":"ads","operationId":"listValueRuleSets","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"List value rule sets","description":"Lists a Meta ad account's value rule sets, which raise or lower bids for audience segments you value differently.\n\nLists the ad account's value rule sets (Meta's `/act_X/value_rule_set`). A value rule\nset adjusts the auction bid up or down for audience segments you value differently;\nattach one to an ad set with `valueRuleSetId` on `POST /v1/ads/create` or\n`PUT /v1/ads/ad-sets/{adSetId}`.\n\nRows are returned in the same camelCase shape the `PUT` body takes, ids included, so a\nset round-trips 1:1: **the update is a full replace, not a patch**, so you GET, mutate\nand send the whole thing back.\n\nLimits: 6 rule sets per ad account, 10 rules per set, 4 criteria per rule.\n\n**Rule order is semantic.** Rules are evaluated in array order and only the FIRST\nmatching rule adjusts the bid for an overlapping audience. The order you send is the\norder that is stored and returned.\n\nEligibility: value rule sets apply only to ad sets on the `LOWEST_COST_WITHOUT_CAP`\n(auto-bid) or `COST_CAP` bid strategies. Meta rejects the rest server-side.","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"Meta ad account id (act_<n>)."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Rows per page"},{"name":"after","in":"query","schema":{"type":"string"},"description":"Cursor from paging.after of the previous page. Meta does not document paging on this edge; `after` comes back null when it omits cursors."}],"responses":{"200":{"description":"Value rule sets","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ValueRuleSet"}},"paging":{"type":"object","properties":{"after":{"type":["string","null"],"description":"Cursor for the next page; null when exhausted or when Meta omits paging."}}}}}}}},"400":{"x-summary":"The input is invalid or Meta rejected the query: a bad rule-set ID looks the same as a permission error.","description":"Invalid input, or Meta rejected the query. Meta answers a bad rule-set id with GraphMethodException code 100 / subcode 33, which is indistinguishable between not-found, no-permission, and account-not-enabled."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}},"post":{"x-resource-group":"ads","operationId":"createValueRuleSet","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"Create a value rule set","description":"Creates a Meta value rule set that raises or lowers bids for chosen audience segments, ready to attach to ad sets.\n\nCreates a value rule set on the ad account (Meta's `POST /act_X/value_rule_set`). Attach the returned id to an ad set with `valueRuleSetId` on `POST /v1/ads/create` or `PUT /v1/ads/ad-sets/{adSetId}`.\n\n### Rule order is semantic\n\nRules are evaluated in array order and only the first matching rule adjusts the bid for an overlapping audience.\n\n### Adjustment\n\n`adjustValue` is an unsigned magnitude in percent; the direction lives in `adjustSign`. There is no signed field and 0 is out of range.\n\n- `INCREASE` accepts 1-1000.\n- `DECREASE` accepts 1-90.\n\n### Criteria\n\n`criteriaValueTypes` is positionally paired with `criteriaValues` (same length, same order). Every type is the literal `\"NONE\"` except on `LOCATION`.\n\n`LOCATION` uses `LOCATION_COUNTRY` / `LOCATION_REGION` / `LOCATION_CITY` / `LOCATION_COMSCORE_MARKET` and may mix them within one criterion. Location values are Targeting-Search keys: a two-letter country code for `LOCATION_COUNTRY`, a numeric key for the rest.\n\n`LOCATION_DMA` was replaced by `LOCATION_COMSCORE_MARKET` on 2026-06-22 and rules using DMAs are no longer active, so this API rejects it.\n\n`AUDIENCE_LABEL` values (e.g. `HIGH_VALUE`) are applied to a Custom Audience in Ads Manager. There is no API to provision them, so label strings are passed through unvalidated and a typo produces a rule that never fires.\n\n### Read-only in Ads Manager\n\nAds Manager turns a rule set read-only (this API stays editable) when a rule uses:\n\n- more than 2 criteria\n- a custom age range\n- the placements `FB_MARKETPLACE`, `FB_SEARCH`, `FB_VIDEO` or `IG_EXPLORE`\n\n### Limits\n\n- 6 rule sets per ad account (enforced by Meta, not here)\n- 10 rules per set\n- 4 criteria per rule\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","adAccountId","name","rules"],"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id (posting or ads variant); its platform decides where the campaign is created."},"adAccountId":{"type":"string","description":"Platform ad account id (Meta act_<n>, Google customer id, LinkedIn account id, ...)."},"name":{"type":"string","minLength":1,"maxLength":255},"rules":{"type":"array","minItems":1,"maxItems":10,"description":"Evaluated in order; the first matching rule wins.","items":{"$ref":"#/components/schemas/ValueRule"}}}}}}},"responses":{"201":{"description":"Value rule set created","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"valueRuleSetId":{"type":["string","null"],"description":"The new rule set id. Meta does not document the create response body, so this is null on the (unobserved) case where it omits the id."}}}}}},"400":{"x-summary":"The input is invalid or Meta rejected the create: check the per-account cap, criteria and value rules access.","description":"Invalid input, or Meta rejected the create (per-account rule-set cap, ineligible criteria, or an account that is not enabled for value rules)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/value-rule-sets/{valueRuleSetId}":{"get":{"x-resource-group":"ads","operationId":"getValueRuleSet","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"Read a value rule set","description":"Shows one Meta value rule set with all its rules and criteria, the first step before editing it.\n\nReads one value rule set including every nested rule id and criterion id. This is step\none of any edit: `PUT` is a full replace, so you need the ids before you can keep the\nobjects you are not changing.\n\nMeta's own read returns `GENDER` values lowercase (`\"male\"`) while writes require\n`\"MALE\"`. Values are passed through untouched, so never case-compare a stored rule\nagainst a fetched one.","security":[{"bearerAuth":[]}],"parameters":[{"name":"valueRuleSetId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform value rule set id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."}],"responses":{"200":{"description":"Value rule set","content":{"application/json":{"schema":{"type":"object","properties":{"valueRuleSet":{"$ref":"#/components/schemas/ValueRuleSet"}}}}}},"400":{"x-summary":"The input is invalid or Meta rejected the read: a bad ID looks the same as a permission error.","description":"Invalid input, or Meta rejected the read. A bad id comes back as GraphMethodException code 100 / subcode 33, which cannot be told apart from a permission problem."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}},"put":{"x-resource-group":"ads","operationId":"updateValueRuleSet","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"Replace a value rule set","description":"Replaces a Meta value rule set with the rules you send, so any rule left out is deleted.\n\n**THIS IS A FULL REPLACE, NOT A PATCH.** Meta's update is declarative: the body you\nsend becomes the rule set.\n\n- `GET /v1/ads/value-rule-sets/{valueRuleSetId}` FIRST.\n- Keep a rule or criterion by echoing its `id`.\n- Create one by including the object WITHOUT an `id`.\n- Delete one by OMITTING it from the array. There is no warning and no undo.\n\n`name` and `rules` are both required for exactly this reason: a partial body would\nsilently destroy every rule left out.\n\n**Rule order is semantic**: the array order you send is the evaluation order, and only\nthe first matching rule adjusts the bid for an overlapping audience.\n\nExisting rule sets created elsewhere may contain `LOCATION_DMA` criteria. Those went\ninert on 2026-06-22 and are rejected here; migrate them to `LOCATION_COMSCORE_MARKET`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"valueRuleSetId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform value rule set id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","name","rules"],"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id (posting or ads variant); its platform decides where the campaign is created."},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Required: the update replaces the whole set."},"rules":{"type":"array","minItems":1,"maxItems":10,"description":"The COMPLETE rule list. Omitting a rule deletes it on Meta.","items":{"$ref":"#/components/schemas/ValueRule"}}}}}}},"responses":{"200":{"description":"Value rule set replaced","content":{"application/json":{"schema":{"type":"object","properties":{"valueRuleSetId":{"type":"string"},"name":{"type":"string"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/ValueRule"}},"message":{"type":"string"}}}}}},"400":{"description":"Invalid input, or Meta rejected the update"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}},"delete":{"x-resource-group":"ads","operationId":"deleteValueRuleSet","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"Delete a value rule set","description":"Deletes a Meta value rule set (detach it from ad sets first, since they are not changed here).\n\nDeletes the rule set (Meta's `POST /{value-rule-set-id}/delete_rule_set`, a custom\naction edge rather than an HTTP DELETE on its side). Ad sets pointing at it are not\nmodified here; detach them first with `valueRulesApplied: false` on\n`PUT /v1/ads/ad-sets/{adSetId}`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"valueRuleSetId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform value rule set id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."}],"responses":{"200":{"description":"Value rule set deleted","content":{"application/json":{"schema":{"type":"object","properties":{"valueRuleSetId":{"type":"string"},"message":{"type":"string"}}}}}},"400":{"x-summary":"The input is invalid or Meta rejected the delete: a bad ID looks the same as a permission error.","description":"Invalid input, or Meta rejected the delete. A bad id comes back as GraphMethodException code 100 / subcode 33, which reads like a permission error rather than a 404."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/accounts/negative-keyword-lists":{"get":{"x-resource-group":"ads","operationId":"listAdNegativeKeywordLists","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"List negative keyword lists","description":"Lists the shared negative keyword lists in a Google Ads account, which you can apply to many campaigns at once.\n\nGoogle Ads shared negative keyword lists (shared_set type NEGATIVE_KEYWORDS). Reads are cached for 10 minutes; quota exhaustion may return the last successful result for up to 7 days with stale=true. Customer selection is limited to this connection and its account scope.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio SocialAccount id."}},{"name":"adAccountId","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."}},{"name":"customerId","in":"query","deprecated":true,"required":false,"schema":{"type":"string","pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"}},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit"],"description":"Optional courtesy field. The resolved account or campaign determines support; other platforms return 501."}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"lists":{"type":"array","items":{"$ref":"#/components/schemas/AdNegativeKeywordList"}},"customerId":{"type":"string","pattern":"^\\d+$","description":"Resolved Google Ads customer id."},"cachedAt":{"type":["string","null"],"format":"date-time","description":"Last successful fetch time, or null without cache storage."},"stale":{"type":"boolean","description":"True when quota exhaustion caused the last successful cached result to be served."}}},"example":{"lists":[{"id":"1234567890","resourceName":"customers/9122445560/sharedSets/1234567890","name":"Excluded searches","memberCount":2,"referenceCount":0}],"customerId":"9122445560","cachedAt":"2026-09-09T10:00:00Z","stale":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access or account permission is missing, or the ad account is not selected: select it or use another connection.","description":"Ads access and permission to the selected account are required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"x-summary":"The campaign or account selection is ambiguous, or the account needs reconnecting: use a profile-scoped key or reconnect it.","description":"Ambiguous campaign or account selection. Use a profile-scoped key. A list still attached to a campaign may also be rejected by Google. The account may also be inactive or need reconnection (code ads_connection_required). Reconnect it and read GET /v1/accounts for its current ID before retrying."},"422":{"description":"Google Ads connection is missing or unavailable."},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Available only on Google Ads."}}},"post":{"x-resource-group":"ads","operationId":"createAdNegativeKeywordList","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"Create a negative keyword list","description":"Creates a shared Google Ads negative keyword list, optionally with starting keywords; it is not attached to any campaign yet.\n\nCreates one Google Ads shared negative keyword list with optional initial keywords in a single atomic mutation. Daily quota is reserved for every mutate item, so large batches may return 429 before any change. This operation is not idempotent. The list is not attached to any campaign.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["accountId","name"],"properties":{"accountId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio SocialAccount id."},"adAccountId":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."},"customerId":{"type":"string","deprecated":true,"pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"},"platform":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit"],"description":"Optional courtesy field. The resolved account or campaign determines support; other platforms return 501."},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Nonempty list name, trimmed before use."},"keywords":{"type":"array","maxItems":5000,"items":{"$ref":"#/components/schemas/KeywordEntry"},"description":"Full desired keyword set. Bare strings use broad match. Send [] to clear the list."}}},"example":{"accountId":"69ce75d483e990e1c01ccfe4","adAccountId":"9122445560","name":"Excluded searches","keywords":["free",{"text":"jobs","matchType":"phrase"}]}}}},"responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^\\d+$","description":"New shared set id."},"resourceName":{"type":"string","description":"New shared set resource name."},"created":{"type":"integer","description":"Number of initial keyword criteria created."},"customerId":{"type":"string","pattern":"^\\d+$","description":"Resolved Google Ads customer id."}}},"example":{"id":"1234567890","resourceName":"customers/9122445560/sharedSets/1234567890","created":2,"customerId":"9122445560"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access or account permission is missing, or the ad account is not selected: select it or use another connection.","description":"Ads access and permission to the selected account are required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection), or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"x-summary":"The campaign or account selection is ambiguous, or the account needs reconnecting: use a profile-scoped key or reconnect it.","description":"Ambiguous campaign or account selection. Use a profile-scoped key. A list still attached to a campaign may also be rejected by Google. The account may also be inactive or need reconnection (code ads_connection_required). Reconnect it and read GET /v1/accounts for its current ID before retrying."},"422":{"description":"Google Ads connection is missing or unavailable."},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Available only on Google Ads."}}}},"/v1/ads/accounts/negative-keyword-lists/{listId}":{"get":{"x-resource-group":"ads","operationId":"getAdNegativeKeywordList","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"Get a negative keyword list","description":"Shows one shared Google Ads negative keyword list with all of its keywords.\n\nGoogle Ads shared negative keyword lists (shared_set type NEGATIVE_KEYWORDS). Reads are cached for 10 minutes; quota exhaustion may return the last successful result for up to 7 days with stale=true. Customer selection is limited to this connection and its account scope. Includes the keywords and their criterion ids.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"listId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$","description":"Google shared set id."}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio SocialAccount id."}},{"name":"adAccountId","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."}},{"name":"customerId","in":"query","deprecated":true,"required":false,"schema":{"type":"string","pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"}},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit"],"description":"Optional courtesy field. The resolved account or campaign determines support; other platforms return 501."}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"list":{"allOf":[{"$ref":"#/components/schemas/AdNegativeKeywordList"},{"type":"object","properties":{"keywords":{"type":"array","items":{"$ref":"#/components/schemas/AdNegativeKeywordListKeyword"}}}}]},"customerId":{"type":"string","pattern":"^\\d+$","description":"Resolved Google Ads customer id."},"cachedAt":{"type":["string","null"],"format":"date-time","description":"Last successful fetch time, or null without cache storage."},"stale":{"type":"boolean","description":"True when quota exhaustion caused the last successful cached result to be served."}}},"example":{"list":{"id":"1234567890","resourceName":"customers/9122445560/sharedSets/1234567890","name":"Excluded searches","memberCount":2,"referenceCount":0,"keywords":[{"criterionId":"111","text":"free","matchType":"broad"},{"criterionId":"222","text":"jobs","matchType":"phrase"}]},"customerId":"9122445560","cachedAt":"2026-09-09T10:00:00Z","stale":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access or account permission is missing, or the ad account is not selected: select it or use another connection.","description":"Ads access and permission to the selected account are required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix it, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"x-summary":"The campaign or account selection is ambiguous, or the account needs reconnecting: use a profile-scoped key or reconnect it.","description":"Ambiguous campaign or account selection. Use a profile-scoped key. A list still attached to a campaign may also be rejected by Google. The account may also be inactive or need reconnection (code ads_connection_required). Reconnect it and read GET /v1/accounts for its current ID before retrying."},"422":{"description":"Google Ads connection is missing or unavailable."},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Available only on Google Ads."}}},"put":{"x-resource-group":"ads","operationId":"updateAdNegativeKeywordList","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"Rename a negative keyword list","description":"Renames a shared Google Ads negative keyword list without changing its keywords or the campaigns using it.\n\nKeywords and campaign associations are unchanged. Use the keywords endpoint to edit the desired keyword set.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"listId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$","description":"Google shared set id."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["accountId","name"],"properties":{"accountId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio SocialAccount id."},"adAccountId":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."},"customerId":{"type":"string","deprecated":true,"pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"},"platform":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit"],"description":"Optional courtesy field. The resolved account or campaign determines support; other platforms return 501."},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Nonempty list name, trimmed before use."}}},"example":{"accountId":"69ce75d483e990e1c01ccfe4","adAccountId":"9122445560","name":"Excluded searches renamed"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"boolean"},"customerId":{"type":"string","pattern":"^\\d+$","description":"Resolved Google Ads customer id."}}},"example":{"updated":true,"customerId":"9122445560"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access or account permission is missing, or the ad account is not selected: select it or use another connection.","description":"Ads access and permission to the selected account are required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"x-summary":"The campaign or account selection is ambiguous, or the account needs reconnecting: use a profile-scoped key or reconnect it.","description":"Ambiguous campaign or account selection. Use a profile-scoped key. A list still attached to a campaign may also be rejected by Google. The account may also be inactive or need reconnection (code ads_connection_required). Reconnect it and read GET /v1/accounts for its current ID before retrying."},"422":{"description":"Google Ads connection is missing or unavailable."},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Available only on Google Ads."}}},"delete":{"x-resource-group":"ads","operationId":"deleteAdNegativeKeywordList","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"Delete a negative keyword list","description":"Deletes a shared Google Ads negative keyword list; detach it from every campaign first.\n\nDetach it from all campaigns first; an in-use list is rejected. Only NEGATIVE_KEYWORDS shared sets are supported.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"listId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$","description":"Google shared set id."}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio SocialAccount id."}},{"name":"adAccountId","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."}},{"name":"customerId","in":"query","deprecated":true,"required":false,"schema":{"type":"string","pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"}},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit"],"description":"Optional courtesy field. The resolved account or campaign determines support; other platforms return 501."}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"boolean"},"customerId":{"type":"string","pattern":"^\\d+$","description":"Resolved Google Ads customer id."}}},"example":{"removed":true,"customerId":"9122445560"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access or account permission is missing, or the ad account is not selected: select it or use another connection.","description":"Forbidden. One of:\n\n- Ads access and permission to the selected account are required.\n- Code `ad_account_not_selected`: the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"x-summary":"The campaign or account selection is ambiguous, or the account needs reconnecting: use a profile-scoped key or reconnect it.","description":"Ambiguous campaign or account selection. Use a profile-scoped key. A list still attached to a campaign may also be rejected by Google. The account may also be inactive or need reconnection (code ads_connection_required). Reconnect it and read GET /v1/accounts for its current ID before retrying."},"422":{"description":"Google Ads connection is missing or unavailable."},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Available only on Google Ads."}}}},"/v1/ads/accounts/negative-keyword-lists/{listId}/keywords":{"put":{"x-resource-group":"ads","operationId":"replaceAdNegativeKeywordListKeywords","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"Replace negative list keywords","description":"Replaces all keywords in a shared Google Ads negative keyword list (or clears it), affecting every campaign that uses the list.\n\n- Existing keywords are diffed by normalized text and match type.\n- Creates and removals are applied atomically in one mutation. Unchanged criteria retain their ids.\n- Send an empty keywords array to clear the list.\n- Changes affect every campaign using this list.\n\n### Quota\n\nEach create or removal consumes one daily operation; the entire batch must fit the remaining quota.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"listId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$","description":"Google shared set id."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["accountId","keywords"],"properties":{"accountId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio SocialAccount id."},"adAccountId":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."},"customerId":{"type":"string","deprecated":true,"pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"},"platform":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit"],"description":"Optional courtesy field. The resolved account or campaign determines support; other platforms return 501."},"keywords":{"type":"array","maxItems":5000,"items":{"$ref":"#/components/schemas/KeywordEntry"},"description":"Full desired keyword set. Bare strings use broad match. Send [] to clear the list."}}},"example":{"accountId":"69ce75d483e990e1c01ccfe4","adAccountId":"9122445560","keywords":["free",{"text":"jobs","matchType":"phrase"}]}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"integer","description":"New criteria or campaign links created."},"removed":{"type":"integer","description":"Existing criteria or campaign links removed."},"customerId":{"type":"string","pattern":"^\\d+$","description":"Resolved Google Ads customer id."}}},"example":{"created":1,"removed":1,"customerId":"9122445560"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access or account permission is missing, or the ad account is not selected: select it or use another connection.","description":"Ads access and permission to the selected account are required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix it, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"x-summary":"The campaign or account selection is ambiguous, or the account needs reconnecting: use a profile-scoped key or reconnect it.","description":"Ambiguous campaign or account selection. Use a profile-scoped key. A list still attached to a campaign may also be rejected by Google. The account may also be inactive or need reconnection (code ads_connection_required). Reconnect it and read GET /v1/accounts for its current ID before retrying."},"422":{"description":"Google Ads connection is missing or unavailable."},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Available only on Google Ads."}}}},"/v1/ads/campaigns/{campaignId}/negative-keyword-lists":{"get":{"x-resource-group":"ads","operationId":"listCampaignNegativeKeywordLists","tags":["Ad Campaigns"],"x-platforms":["google"],"summary":"List campaign negative lists","description":"Lists the shared negative keyword lists attached to a Google campaign, separate from its own campaign-level negatives.\n\nGoogle Ads shared negative keyword lists (shared_set type NEGATIVE_KEYWORDS). Reads are cached for 10 minutes; quota exhaustion may return the last successful result for up to 7 days with stale=true. Customer selection is limited to this connection and its account scope.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$","description":"Google campaign id."}},{"name":"platform","in":"query","schema":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit"],"description":"Optional courtesy field. The resolved account or campaign determines support; other platforms return 501."}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"lists":{"type":"array","items":{"$ref":"#/components/schemas/AdNegativeKeywordList"}},"customerId":{"type":"string","pattern":"^\\d+$","description":"Resolved Google Ads customer id."},"cachedAt":{"type":["string","null"],"format":"date-time","description":"Last successful fetch time, or null without cache storage."},"stale":{"type":"boolean","description":"True when quota exhaustion caused the last successful cached result to be served."}}},"example":{"lists":[{"id":"1234567890","resourceName":"customers/9122445560/sharedSets/1234567890","name":"Excluded searches","memberCount":2,"referenceCount":1}],"customerId":"9122445560","cachedAt":"2026-09-09T10:00:00Z","stale":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access or account permission is missing, or the ad account is not selected: select it or use another connection.","description":"Ads access and permission to the selected account are required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"x-summary":"The campaign or account selection is ambiguous, or the account needs reconnecting: use a profile-scoped key or reconnect it.","description":"Ambiguous campaign or account selection. Use a profile-scoped key. A list still attached to a campaign may also be rejected by Google. The account may also be inactive or need reconnection (code ads_connection_required). Reconnect it and read GET /v1/accounts for its current ID before retrying."},"422":{"description":"Google Ads connection is missing or unavailable."},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Available only on Google Ads."}}},"put":{"x-resource-group":"ads","operationId":"replaceCampaignNegativeKeywordLists","tags":["Ad Campaigns"],"x-platforms":["google"],"summary":"Replace campaign negative lists","description":"Sets exactly which shared negative keyword lists apply to a Google campaign, or detaches them all, without changing the lists themselves.\n\nSend listIds=[] to detach all negative keyword lists. Only campaign_shared_set links are changed; the lists and their keywords are preserved. Every list must belong to the campaign customer and have type NEGATIVE_KEYWORDS.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$","description":"Google campaign id."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["listIds"],"properties":{"platform":{"type":"string","enum":["facebook","instagram","tiktok","linkedin","pinterest","google","twitter","openai","reddit"],"description":"Optional courtesy field. The resolved account or campaign determines support; other platforms return 501."},"listIds":{"type":"array","maxItems":20,"items":{"type":"string","pattern":"^\\d+$","description":"Shared negative keyword list id."}}}},"example":{"platform":"google","listIds":["1234567890"]}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"integer","description":"New criteria or campaign links created."},"removed":{"type":"integer","description":"Existing criteria or campaign links removed."},"customerId":{"type":"string","pattern":"^\\d+$","description":"Resolved Google Ads customer id."}}},"example":{"created":1,"removed":0,"customerId":"9122445560"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access or account permission is missing, or the ad account is not selected: select it or use another connection.","description":"Ads access and permission to the selected account are required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection), or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"x-summary":"The campaign or account selection is ambiguous, or the account needs reconnecting: use a profile-scoped key or reconnect it.","description":"Ambiguous campaign or account selection. Use a profile-scoped key. A list still attached to a campaign may also be rejected by Google. The account may also be inactive or need reconnection (code ads_connection_required). Reconnect it and read GET /v1/accounts for its current ID before retrying."},"422":{"description":"Google Ads connection is missing or unavailable."},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Available only on Google Ads."}}}},"/v1/ads/accounts/callouts":{"get":{"x-resource-group":"ads","operationId":"listAccountCallouts","summary":"List account callouts","tags":["Ad Accounts"],"x-platforms":["google"],"description":"Lists the callouts attached at account level in Google Ads, which can show on ads across all campaigns.\n\nFresh reads are cached for 10 minutes; exhausted quota may return the last successful read with stale=true. Inherited assets are not included. Preserves Google RMF C.75 account-level callouts.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio Google Ads connection id."}},{"name":"adAccountId","in":"query","schema":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."}},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string","pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"}}],"responses":{"200":{"description":"Assets returned.","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"callouts":{"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string"},"status":{"type":"string"},"text":{"type":"string"}}}},"cachedAt":{"type":["string","null"],"format":"date-time","description":"Time of the cached Google read. Null when no cache was used."},"stale":{"type":"boolean","description":"True when exhausted quota required returning the last successful read."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads access is required."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Only supported on Google Ads."}}},"post":{"x-resource-group":"ads","operationId":"addAccountCallouts","summary":"Add account callouts","tags":["Ad Accounts"],"x-platforms":["google"],"description":"Creates callouts and attaches them at account level in Google Ads so they can show on ads across all campaigns.\n\nCreates assets and customer_asset links for this Google customer. Links apply at account level.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","callouts"],"properties":{"accountId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio Google Ads connection id."},"adAccountId":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."},"customerId":{"type":"string","deprecated":true,"pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"},"callouts":{"type":"array","items":{"type":"string","minLength":1,"maxLength":25},"minItems":1,"maxItems":20}}},"example":{"accountId":"64b1f0c8a1b2c3d4e5f60718","adAccountId":"1234567890","callouts":["Fast setup"]}}}},"responses":{"201":{"description":"Assets created and attached.","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"callouts":{"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string"},"text":{"type":"string"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Ads access is required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Only supported on Google Ads."}}},"put":{"x-resource-group":"ads","operationId":"updateAccountCallouts","summary":"Update account callouts","tags":["Ad Accounts"],"x-platforms":["google"],"description":"Edits existing Google Ads callouts in place; the change applies everywhere that callout is used.\n\nSend updates with assetResourceName and the fields to change. An asset is shared: changes affect every attachment using it. Omitted fields stay unchanged. The operation consumes the Google operations budget and invalidates affected cached lists.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","updates"],"properties":{"accountId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio Google Ads connection id."},"adAccountId":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."},"customerId":{"type":"string","deprecated":true,"pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"},"updates":{"type":"array","items":{"type":"object","required":["assetResourceName"],"properties":{"assetResourceName":{"type":"string","pattern":"^customers/\\d+/assets/\\d+$","description":"Asset resource name returned by a list operation. Must belong to the selected customer."},"calloutAsset":{"type":"object","required":["calloutText"],"properties":{"calloutText":{"type":"string","minLength":1,"maxLength":25}}}},"description":"Provide at least one field belonging to this asset type."},"minItems":1,"maxItems":20}}},"example":{"accountId":"64b1f0c8a1b2c3d4e5f60718","adAccountId":"1234567890","updates":[{"assetResourceName":"customers/1234567890/assets/123","calloutAsset":{"calloutText":"Simple integration"}}]}}}},"responses":{"200":{"description":"Assets returned.","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"integer"},"customerId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Ads access is required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection), or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Only supported on Google Ads."}}},"delete":{"x-resource-group":"ads","operationId":"removeAccountCallout","summary":"Remove account callout","tags":["Ad Accounts"],"x-platforms":["google"],"description":"Detaches a callout from the Google Ads account level, leaving it on any campaigns or ad groups that still use it.\n\nRemoves the customer_asset attachment only. The underlying shared asset and its campaign or ad-group attachments remain. Fields go in the query string. A JSON body with the same fields is also accepted and, when sent, the query string is ignored.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"description":"Zernio Google Ads connection id."},{"name":"adAccountId","in":"query","schema":{"type":"string","pattern":"^\\d+$"},"description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Alias of adAccountId, kept for existing callers"},{"name":"assetId","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Numeric Google Ads asset id."}],"responses":{"200":{"description":"Assets returned.","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"boolean"},"customerId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Ads access is required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix it, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Only supported on Google Ads."}}}},"/v1/ads/accounts/sitelinks":{"get":{"x-resource-group":"ads","operationId":"listAccountSitelinks","summary":"List account sitelinks","tags":["Ad Accounts"],"x-platforms":["google"],"description":"Lists the sitelinks attached at account level in Google Ads, which can show on ads across all campaigns.\n\nFresh reads are cached for 10 minutes; exhausted quota may return the last successful read with stale=true. Inherited assets are not included.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio Google Ads connection id."}},{"name":"adAccountId","in":"query","schema":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."}},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string","pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"}}],"responses":{"200":{"description":"Assets returned.","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"sitelinks":{"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string"},"status":{"type":"string"},"assetResourceName":{"type":"string"},"customerAssetResourceName":{"type":"string"},"text":{"type":"string"},"linkUrl":{"type":"string","format":"uri"},"description1":{"type":"string"},"description2":{"type":"string"}}}},"cachedAt":{"type":["string","null"],"format":"date-time","description":"Time of the cached Google read. Null when no cache was used."},"stale":{"type":"boolean","description":"True when exhausted quota required returning the last successful read."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads access is required."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Only supported on Google Ads."}}},"post":{"x-resource-group":"ads","operationId":"addAccountSitelinks","summary":"Add account sitelinks","tags":["Ad Accounts"],"x-platforms":["google"],"description":"Creates sitelinks and attaches them at account level in Google Ads so they can show on ads across all campaigns.\n\nCreates assets and customer_asset links for this Google customer. Links apply at account level.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","sitelinks"],"properties":{"accountId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio Google Ads connection id."},"adAccountId":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."},"customerId":{"type":"string","deprecated":true,"pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"},"sitelinks":{"type":"array","items":{"$ref":"#/components/schemas/GoogleSitelink"},"minItems":1,"maxItems":20}}},"example":{"accountId":"64b1f0c8a1b2c3d4e5f60718","adAccountId":"1234567890","sitelinks":[{"text":"Pricing","linkUrl":"https://zernio.com/pricing"}]}}}},"responses":{"201":{"description":"Assets created and attached.","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"sitelinks":{"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string"},"text":{"type":"string","minLength":1,"maxLength":25},"linkUrl":{"type":"string","format":"uri"},"description1":{"type":"string","minLength":1,"maxLength":35},"description2":{"type":"string","minLength":1,"maxLength":35}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Ads access is required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Only supported on Google Ads."}}},"put":{"x-resource-group":"ads","operationId":"updateAccountSitelinks","summary":"Update account sitelinks","tags":["Ad Accounts"],"x-platforms":["google"],"description":"Edits existing Google Ads sitelinks in place; the change applies everywhere that sitelink is used.\n\nSend updates with assetResourceName and the fields to change. An asset is shared: changes affect every attachment using it. Omitted fields stay unchanged. The operation consumes the Google operations budget and invalidates affected cached lists.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","updates"],"properties":{"accountId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio Google Ads connection id."},"adAccountId":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."},"customerId":{"type":"string","deprecated":true,"pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"},"updates":{"type":"array","items":{"type":"object","required":["assetResourceName"],"properties":{"assetResourceName":{"type":"string","pattern":"^customers/\\d+/assets/\\d+$","description":"Asset resource name returned by a list operation. Must belong to the selected customer."},"sitelinkAsset":{"type":"object","properties":{"linkText":{"type":"string","minLength":1,"maxLength":25},"description1":{"type":"string","maxLength":35},"description2":{"type":"string","maxLength":35},"linkUrl":{"type":"string","format":"uri","description":"Alias for finalUrls with one URL. Do not supply both."}},"minProperties":1},"finalUrls":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1}},"description":"Provide at least one field belonging to this asset type."},"minItems":1,"maxItems":20}}},"example":{"accountId":"64b1f0c8a1b2c3d4e5f60718","adAccountId":"1234567890","updates":[{"assetResourceName":"customers/1234567890/assets/123","sitelinkAsset":{"linkText":"Explore pricing"},"finalUrls":["https://zernio.com/pricing"]}]}}}},"responses":{"200":{"description":"Assets returned.","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"integer"},"customerId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Forbidden. One of:\n\n- Ads access is required.\n- Code `ad_account_not_selected`: the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Only supported on Google Ads."}}},"delete":{"x-resource-group":"ads","operationId":"removeAccountSitelink","summary":"Remove account sitelink","tags":["Ad Accounts"],"x-platforms":["google"],"description":"Detaches a sitelink from the Google Ads account level, leaving it on any campaigns or ad groups that still use it.\n\nRemoves the customer_asset attachment only. The underlying shared asset and its campaign or ad-group attachments remain. Fields go in the query string. A JSON body with the same fields is also accepted and, when sent, the query string is ignored.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"description":"Zernio Google Ads connection id."},{"name":"adAccountId","in":"query","schema":{"type":"string","pattern":"^\\d+$"},"description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Alias of adAccountId, kept for existing callers"},{"name":"assetId","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Numeric Google Ads asset id."}],"responses":{"200":{"description":"Assets returned.","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"boolean"},"customerId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Ads access is required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix it, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Only supported on Google Ads."}}}},"/v1/ads/accounts/structured-snippets":{"get":{"x-resource-group":"ads","operationId":"listAccountStructuredSnippets","summary":"List account snippets","tags":["Ad Accounts"],"x-platforms":["google"],"description":"Lists the structured snippets attached at account level in Google Ads, which can show on ads across all campaigns.\n\nFresh reads are cached for 10 minutes; exhausted quota may return the last successful read with stale=true. Inherited assets are not included.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio Google Ads connection id."}},{"name":"adAccountId","in":"query","schema":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."}},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string","pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"}}],"responses":{"200":{"description":"Assets returned.","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"structuredSnippets":{"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string"},"status":{"type":"string"},"assetResourceName":{"type":"string"},"customerAssetResourceName":{"type":"string"},"header":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}}}},"cachedAt":{"type":["string","null"],"format":"date-time","description":"Time of the cached Google read. Null when no cache was used."},"stale":{"type":"boolean","description":"True when exhausted quota required returning the last successful read."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads access is required."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Only supported on Google Ads."}}},"post":{"x-resource-group":"ads","operationId":"addAccountStructuredSnippets","summary":"Add account snippets","tags":["Ad Accounts"],"x-platforms":["google"],"description":"Creates structured snippets and attaches them at account level in Google Ads so they can show on ads across all campaigns.\n\nCreates assets and customer_asset links for this Google customer. Links apply at account level.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","structuredSnippets"],"properties":{"accountId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio Google Ads connection id."},"adAccountId":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."},"customerId":{"type":"string","deprecated":true,"pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"},"structuredSnippets":{"type":"array","items":{"$ref":"#/components/schemas/GoogleStructuredSnippet"},"minItems":1,"maxItems":20}}},"example":{"accountId":"64b1f0c8a1b2c3d4e5f60718","adAccountId":"1234567890","structuredSnippets":[{"header":"Types","values":["Scheduling","Analytics","Messaging"]}]}}}},"responses":{"201":{"description":"Assets created and attached.","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"structuredSnippets":{"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string"},"header":{"type":"string","enum":["Amenities","Brands","Courses","Degree programs","Destinations","Featured hotels","Insurance coverage","Models","Neighborhoods","Service catalog","Shows","Styles","Types"]},"values":{"type":"array","minItems":3,"maxItems":10,"items":{"type":"string","minLength":1,"maxLength":25}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Ads access is required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Only supported on Google Ads."}}},"put":{"x-resource-group":"ads","operationId":"updateAccountStructuredSnippets","summary":"Update account snippets","tags":["Ad Accounts"],"x-platforms":["google"],"description":"Edits existing Google Ads structured snippets in place; the change applies everywhere that snippet is used.\n\nSend updates with assetResourceName and the fields to change. An asset is shared: changes affect every attachment using it. Omitted fields stay unchanged. The operation consumes the Google operations budget and invalidates affected cached lists.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","updates"],"properties":{"accountId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Zernio Google Ads connection id."},"adAccountId":{"type":"string","pattern":"^\\d+$","description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."},"customerId":{"type":"string","deprecated":true,"pattern":"^\\d+$","description":"Alias of adAccountId, kept for existing callers"},"updates":{"type":"array","items":{"type":"object","required":["assetResourceName"],"properties":{"assetResourceName":{"type":"string","pattern":"^customers/\\d+/assets/\\d+$","description":"Asset resource name returned by a list operation. Must belong to the selected customer."},"structuredSnippetAsset":{"$ref":"#/components/schemas/GoogleStructuredSnippet"}},"description":"Provide at least one field belonging to this asset type."},"minItems":1,"maxItems":20}}},"example":{"accountId":"64b1f0c8a1b2c3d4e5f60718","adAccountId":"1234567890","updates":[{"assetResourceName":"customers/1234567890/assets/123","structuredSnippetAsset":{"header":"Types","values":["Scheduling","Reporting","Messaging"]}}]}}}},"responses":{"200":{"description":"Assets returned.","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"integer"},"customerId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Ads access is required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection), or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Only supported on Google Ads."}}},"delete":{"x-resource-group":"ads","operationId":"removeAccountStructuredSnippet","summary":"Remove account snippet","tags":["Ad Accounts"],"x-platforms":["google"],"description":"Detaches a structured snippet from the Google Ads account level, leaving it on any campaigns or ad groups that still use it.\n\nRemoves the customer_asset attachment only. The underlying shared asset and its campaign or ad-group attachments remain. Fields go in the query string. A JSON body with the same fields is also accepted and, when sent, the query string is ignored.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"description":"Zernio Google Ads connection id."},{"name":"adAccountId","in":"query","schema":{"type":"string","pattern":"^\\d+$"},"description":"Platform ad account ID (Google customer ID, digits only). Required when the connection has multiple customers."},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Alias of adAccountId, kept for existing callers"},{"name":"assetId","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Numeric Google Ads asset id."}],"responses":{"200":{"description":"Assets returned.","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"boolean"},"customerId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Ads access is required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix it, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or platform quota exhausted."},"501":{"description":"Only supported on Google Ads."}}}},"/v1/ads/accounts/hierarchy":{"get":{"x-resource-group":"ads","operationId":"getAdAccountHierarchy","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"Get manager account hierarchy","description":"Shows the Google Ads manager (MCC) and client account tree for a connection, including pending invitations and link status.\n\n### How the tree is built\n\nIt starts from every customer the Google user behind the connection can access directly and walks each tree to any depth with `customer_client`. It then reads each manager's own client links, so every client carries its direct parent, the `managerLinkId` and the link status.\n\n- Invitations a manager sent that the client has not accepted yet appear as clients with `linkStatus: PENDING` (Google returns no name or currency for them).\n- Refused, canceled and ended links are history and are omitted.\n- A directly accessible account that is also nested in another tree appears only once, inside that tree.\n\n### Response fields\n\n- `managerLinks` (on a root): the managers linked to that account, including invitations it can still accept with PATCH /v1/ads/accounts/manager-links.\n- `directCustomers`: every account the Google user accesses directly (the ones this connection can accept or decline invitations for) with their pending invitations, including accounts that are also nested in a tree.\n- `unavailable`: customers Google refuses to read (for example a cancelled account), with Google's reason, instead of failing the call.\n- `truncated`: true when more exist than the limit. Up to 50 roots and 50 managers per root are read.\n- `cachedAt` and `stale`: the response is cached for 10 minutes per connection.\n\nWhen the connection is scoped to specific ad accounts, client accounts outside that scope are hidden (managers stay visible).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Google ads SocialAccount id."},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"Only return the tree rooted at this customer id (digits only). It must be an account the Google user accesses directly. Omit to list every tree."},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string"},"description":"Alias of adAccountId, kept for consistency with the other Google Ads account endpoints."}],"responses":{"200":{"description":"Manager and client hierarchy","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"},"roots":{"type":"array","items":{"type":"object","properties":{"customerId":{"type":"string","description":"Native Google Ads customer id, digits only."},"name":{"type":["string","null"]},"currency":{"type":["string","null"],"description":"ISO 4217 code."},"timeZone":{"type":["string","null"],"description":"IANA time zone, e.g. Europe/Madrid."},"manager":{"type":"boolean","description":"True for a manager (MCC) account."},"testAccount":{"type":"boolean"},"status":{"type":["string","null"],"description":"Google customer status: ENABLED, CANCELED, SUSPENDED or CLOSED."},"managerLinks":{"type":"array","description":"Managers linked to this account, ACTIVE or PENDING.","items":{"type":"object","properties":{"managerCustomerId":{"type":"string"},"managerLinkId":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","PENDING"]}}}},"clients":{"type":"array","description":"Every account under this root at any depth, in Google's order, followed by pending invitations.","items":{"$ref":"#/components/schemas/GoogleAdsHierarchyClient"}}}}},"directCustomers":{"type":"array","items":{"type":"object","properties":{"customerId":{"type":"string"},"manager":{"type":"boolean"},"pendingInvitations":{"type":"array","description":"Manager invitations this account has not answered yet.","items":{"type":"object","properties":{"managerCustomerId":{"type":"string"},"managerLinkId":{"type":"string"}}}}}}},"unavailable":{"type":"array","items":{"type":"object","properties":{"customerId":{"type":"string"},"reason":{"type":"string","description":"Google's error message and code."}}}},"truncated":{"type":"boolean"},"cachedAt":{"type":["string","null"],"format":"date-time","description":"When this data was fetched from Google. Null on a live read."},"stale":{"type":"boolean","description":"True when Google's quota was exhausted and this is the last successful fetch."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or quota exhausted; retry later."},"501":{"description":"Only available on Google Ads accounts"}}}},"/v1/ads/accounts/manager-links":{"post":{"x-resource-group":"ads","operationId":"inviteAdAccountToManager","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"Invite a client account to a manager","description":"Invites a Google Ads account to be managed by one of your manager accounts; the link stays pending until the client accepts.\n\nSends a manager-to-client link invitation from `managerCustomerId` to `clientCustomerId` (Google's CustomerClientLinkService).\n\n- The manager must be one the connection's Google user reaches, directly or under another manager (see GET /v1/ads/accounts/hierarchy).\n- The client can be any Google Ads account.\n\nThe link stays `PENDING` until someone with access to the client accepts it in Google Ads or through PATCH on this path.\n\nNot idempotent: Google refuses a second invitation while one is pending. Send `validateOnly: true` to have Google check the request without sending anything.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["accountId","managerCustomerId","clientCustomerId"],"properties":{"accountId":{"type":"string","description":"Google ads SocialAccount id."},"managerCustomerId":{"type":"string","description":"Manager customer id, digits only."},"clientCustomerId":{"type":"string","description":"Client customer id to invite, digits only."},"validateOnly":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Validated only (validateOnly true), nothing sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleAdsManagerLink"}}}},"201":{"description":"Invitation sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleAdsManagerLink"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or quota exhausted; retry later."},"501":{"description":"Only available on Google Ads accounts"}}},"patch":{"x-resource-group":"ads","operationId":"updateAdAccountManagerLink","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"Accept, decline, cancel or end a manager link","description":"Accepts, declines or cancels a Google Ads manager invitation, or ends an existing manager-client link.\n\nChanges one manager-client link, identified by `managerCustomerId`, `clientCustomerId` and `managerLinkId` (all from GET /v1/ads/accounts/hierarchy).\n\n### Actions\n\n- `accept` and `decline`: answer a pending invitation as the client (CustomerManagerLinkService). The connection's Google user needs direct access to the client account; access through a manager is not enough, because the link does not exist yet.\n- `cancel`: withdraws a pending invitation, as the manager (CustomerClientLinkService).\n- `unlink`: ends an active link, as the manager (CustomerClientLinkService).\n\nSend `validateOnly: true` to have Google check the change without applying it.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["accountId","managerCustomerId","clientCustomerId","managerLinkId","action"],"properties":{"accountId":{"type":"string","description":"Google ads SocialAccount id."},"managerCustomerId":{"type":"string","description":"Manager customer id, digits only."},"clientCustomerId":{"type":"string","description":"Client customer id, digits only."},"managerLinkId":{"type":"string","description":"Numeric link id from GET /v1/ads/accounts/hierarchy."},"action":{"type":"string","enum":["accept","decline","cancel","unlink"]},"validateOnly":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Link updated, or validated only when validateOnly is true","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleAdsManagerLink"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or quota exhausted; retry later."},"501":{"description":"Only available on Google Ads accounts"}}}},"/v1/ads/accounts/billing":{"get":{"x-resource-group":"ads","operationId":"getAdAccountBilling","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"Get ad account billing","description":"Reads the payments accounts a Google Ads account can be billed to, plus its billing setups and account budgets.\n\n### Payments accounts\n\nPayments accounts come from Google's PaymentsAccountService, read as the manager above the customer. They are the monthly invoicing (consolidated billing) accounts of that manager.\n\nAn empty `paymentsAccounts` means the manager has no monthly invoicing, so billing cannot be set up through the API and has to be added in Google Ads.\n\n### Billing setups and budgets\n\nBilling setups and account budgets are read live from Google with their status. Results are cached for 10 minutes and dropped on every setup through Zernio.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Google ads SocialAccount id."},{"name":"adAccountId","in":"query","required":false,"schema":{"type":"string"},"description":"Google Ads customer id, digits only. Defaults to the connection's selected customer."}],"responses":{"200":{"description":"Billing state of the customer","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"paymentsAccounts":{"type":"array","items":{"type":"object","properties":{"paymentsAccountId":{"type":"string","description":"Format 1234-5678-9012-3456. Pass it to POST /v1/ads/accounts/billing."},"name":{"type":["string","null"]},"currency":{"type":["string","null"]},"paymentsProfileId":{"type":["string","null"]},"payingManagerCustomerId":{"type":["string","null"],"description":"Manager whose monthly invoice pays this account."}}}},"billingSetups":{"type":"array","items":{"type":"object","properties":{"billingSetupId":{"type":"string"},"status":{"type":"string","enum":["PENDING","APPROVED_HELD","APPROVED","CANCELLED","UNKNOWN"],"description":"APPROVED_HELD means approved but waiting for its first account budget to be approved."},"paymentsAccountId":{"type":["string","null"]},"startDateTime":{"type":["string","null"],"description":"In the account time zone, as Google returns it."},"endDateTime":{"type":["string","null"]}}}},"accountBudgets":{"type":"array","items":{"type":"object","properties":{"accountBudgetId":{"type":"string"},"status":{"type":"string","enum":["PENDING","APPROVED","CANCELLED","UNKNOWN"]},"billingSetupId":{"type":["string","null"]},"approvedSpendingLimitMicros":{"type":["string","null"]},"approvedSpendingLimitType":{"type":["string","null"],"description":"INFINITE for an unlimited budget."},"pendingProposalId":{"type":["string","null"],"description":"Account budget proposal still waiting for Google's review."}}}},"pendingBudgetProposals":{"type":"array","description":"New account budgets proposed but not yet approved by Google. A setup with one is not reused by the POST.","items":{"type":"object","properties":{"accountBudgetProposalId":{"type":"string"},"billingSetupId":{"type":["string","null"]}}}},"cachedAt":{"type":["string","null"],"format":"date-time","description":"When this data was fetched from Google. Null when the cache is unavailable."},"stale":{"type":"boolean","description":"True when Google's quota was exhausted and this is the last successful fetch."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or quota exhausted; retry later."},"501":{"description":"Only available on Google Ads accounts"}}},"post":{"x-resource-group":"ads","operationId":"setUpAdAccountBilling","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"Set up ad account billing (monthly invoicing)","description":"Bills a Google Ads account to a monthly invoicing payments account of a manager above it, and proposes its account budget, so the account can serve without anyone opening Google Ads.\n\n### Monthly invoicing only\n\nGoogle's API cannot add a card or other payment method. So `paymentsAccountId` must be one of the manager's monthly invoicing (consolidated billing) payments accounts listed by GET /v1/ads/accounts/billing.\n\nA manager without monthly invoicing has none, and billing has to be added in Google Ads instead.\n\n### What it creates\n\n1. A billing setup (Google's BillingSetupService) that starts now on that payments account.\n2. An account budget proposal that starts now and never ends: unlimited by default, or capped at `spendingLimit` in the account currency.\n\nGoogle reviews the budget offline, usually within an hour. Until then the setup reads `APPROVED_HELD` and ads do not serve.\n\n### Existing billing\n\nThis call never replaces existing billing. It is refused with 409 when:\n\n- the customer's current billing setup already has a budget;\n- the customer is billed to another payments account.\n\nA current setup on the same payments account without a budget (for example after a budget rejection) is reused, so resending the same request finishes it.\n\n### Retries and validation\n\nNot idempotent and never retried: after a 502 with details.creationStatus=unknown, read GET /v1/ads/accounts/billing before retrying.\n\nGoogle has no dry run for billing setups. So `validateOnly: true` checks the payments account and the existing billing without creating anything, and asks Google to validate the budget when a setup would be reused.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["accountId","adAccountId","paymentsAccountId"],"properties":{"accountId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Google ads SocialAccount id."},"adAccountId":{"type":"string","pattern":"^[0-9]+$","description":"Google Ads customer id to bill, digits only."},"paymentsAccountId":{"type":"string","pattern":"^\\d{4}-\\d{4}-\\d{4}-\\d{4}$","description":"Monthly invoicing payments account from GET /v1/ads/accounts/billing."},"spendingLimit":{"type":"number","exclusiveMinimum":0,"description":"Account budget cap in the account currency. Omit for an unlimited budget."},"budgetName":{"type":"string","minLength":1,"maxLength":255,"default":"Zernio account budget"},"purchaseOrderNumber":{"type":"string","minLength":1,"maxLength":64,"description":"Printed on the invoice. No effect on delivery."},"validateOnly":{"type":"boolean","default":false}}},"example":{"accountId":"69ce75d483e990e1c01ccfe4","adAccountId":"5551234567","paymentsAccountId":"1234-5678-9012-3456","spendingLimit":5000}}}},"responses":{"200":{"x-summary":"The validation passed and nothing was created: `billingSetupId` is set when an existing setup would be reused.","description":"validateOnly: checks passed, nothing created. billingSetupId is set when an existing setup would be reused.","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"paymentsAccountId":{"type":"string"},"paymentsAccountName":{"type":["string","null"]},"billingSetupId":{"type":["string","null"]},"reusedBillingSetup":{"type":"boolean"},"accountBudgetProposalId":{"type":["string","null"],"description":"Always null for validateOnly."},"validateOnly":{"type":"boolean"}}}}}},"201":{"description":"Billing setup created (or reused) and account budget proposed.","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"paymentsAccountId":{"type":"string"},"paymentsAccountName":{"type":["string","null"]},"billingSetupId":{"type":"string"},"reusedBillingSetup":{"type":"boolean","description":"True when an existing setup on the same payments account without a budget was completed."},"accountBudgetProposalId":{"type":["string","null"]},"validateOnly":{"type":"boolean"},"nextSteps":{"type":"string"}}}}}},"400":{"x-summary":"The input is invalid, the payments account is unusable, or Google rejected it: fix it, and resend if only the budget failed.","description":"Invalid input, a payments account the customer cannot use (the message lists the available ones), or a Google rejection. A rejected budget after a created setup carries details.billingSetupId: resend the same request to finish.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"x-summary":"The customer already has a billing setup, so nothing was changed.","description":"The customer already has billing: a current billing setup with a budget, or one on another payments account. Nothing is changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Google Ads operations budget or quota exhausted; retry later."},"501":{"description":"Only available on Google Ads accounts"},"502":{"x-summary":"Google did not confirm the billing setup or budget proposal: fetch the account's current billing before retrying.","description":"Google did not confirm the billing setup (details.creationStatus=unknown) or the budget proposal. Read GET /v1/ads/accounts/billing before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/ads/accounts/user-invitations":{"get":{"x-resource-group":"ads","operationId":"listAdAccountUserInvitations","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"List user access invitations","description":"Lists the email invitations to a Google Ads account, with their role and status.\n\nReads Google's `customer_user_access_invitation` resource for one customer. Listed invitations are:\n\n- `PENDING`\n- `DECLINED`\n- `EXPIRED` (Google expires them 20 days after sending)\n\n### Not listed\n\n- An accepted invitation becomes a user of the account and leaves this list, which can take Google up to 24 hours.\n- An invitation still waiting for multi-party approval is not listed until a second admin approves it. GET /v1/ads/accounts/user-invitations/pending-approvals lists those.\n\nResults are cached for 10 minutes and dropped on every invite or revoke through Zernio.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Google ads SocialAccount id."},{"name":"adAccountId","in":"query","required":false,"schema":{"type":"string"},"description":"Google Ads customer id, digits only. Defaults to the connection's selected customer."}],"responses":{"200":{"description":"Invitations of the customer","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"invitations":{"type":"array","items":{"$ref":"#/components/schemas/GoogleAdsUserAccessInvitation"}},"cachedAt":{"type":["string","null"],"format":"date-time","description":"When this data was fetched from Google. Null when the cache is unavailable."},"stale":{"type":"boolean","description":"True when Google's quota was exhausted and this is the last successful fetch."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or quota exhausted; retry later."},"501":{"description":"Only available on Google Ads accounts"}}},"post":{"x-resource-group":"ads","operationId":"inviteAdAccountUser","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"Invite a user to an ad account by email","description":"Emails someone an invitation to a Google Ads account with the access role you choose, for example to hand a client account you created under your manager to its owner.\n\nIt creates a user access invitation (Google's CustomerUserAccessInvitationService) on `adAccountId`. The recipient accepts from the email, possibly with another Google account.\n\n### Access needed\n\nThe connection's Google user needs admin access to that account, directly or through a manager above it. That is the case for an account created with POST /v1/ads/accounts.\n\n### Multi-party approval\n\nWhen Google requires multi-party approval, nothing is sent until a second admin of the account approves the request in Google Ads.\n\nThe response then has `status: PENDING_APPROVAL` and a `multiPartyAuthReviewId` instead of an `invitationId`. DELETE /v1/ads/accounts/user-invitations/pending-approvals withdraws it.\n\n### Retries and validation\n\nNot idempotent: Google refuses a second invitation while the email has one pending or awaiting approval.\n\nGoogle has no server-side check for this call. So `validateOnly: true` reads the account's invitations with the same credentials (proving the account is reachable) and fails if the email already has a pending one, without sending anything.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["accountId","adAccountId","emailAddress","accessRole"],"properties":{"accountId":{"type":"string","description":"Google ads SocialAccount id."},"adAccountId":{"type":"string","description":"Google Ads customer id to invite the user to, digits only."},"emailAddress":{"type":"string","format":"email"},"accessRole":{"$ref":"#/components/schemas/GoogleAdsAccessRole"},"validateOnly":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Validated only (validateOnly true), nothing sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleAdsUserAccessInvitationResult"}}}},"201":{"description":"Invitation sent, or held for multi-party approval","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleAdsUserAccessInvitationResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or quota exhausted; retry later."},"501":{"description":"Only available on Google Ads accounts"}}},"delete":{"x-resource-group":"ads","operationId":"revokeAdAccountUserInvitation","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"Revoke a user access invitation","description":"Withdraws an email invitation to a Google Ads account that has not been accepted yet.\n\nRemoves the invitation `invitationId` (from GET on this path) from `adAccountId`. It no longer works from the email, and the address can be invited again.","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Google ads SocialAccount id."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"Google Ads customer id, digits only."},{"name":"invitationId","in":"query","required":true,"schema":{"type":"string"},"description":"Numeric invitation id from GET /v1/ads/accounts/user-invitations."}],"responses":{"200":{"description":"Invitation revoked","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"invitationId":{"type":"string"},"revoked":{"type":"boolean","description":"Always true."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or quota exhausted; retry later."},"501":{"description":"Only available on Google Ads accounts"}}}},"/v1/ads/accounts/user-invitations/pending-approvals":{"get":{"x-resource-group":"ads","operationId":"listAdAccountUserInvitationApprovals","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"List invitations awaiting multi-party approval","description":"Lists the email invitations to a Google Ads account that Google is holding until a second admin approves them.\n\nWhen Google requires multi-party approval, POST /v1/ads/accounts/user-invitations answers `status: PENDING_APPROVAL` and sends nothing. Those requests are not in GET /v1/ads/accounts/user-invitations.\n\nThis reads Google's `multi_party_auth_review` resource for the ones still `PENDING` that target an invitation. Approved, rejected, revoked and expired reviews are not listed.\n\n### Caching\n\nResults are cached for 10 minutes and dropped on every invite or withdrawal through Zernio. An approval or rejection made in Google Ads can take that long to show.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Google ads SocialAccount id."},{"name":"adAccountId","in":"query","required":false,"schema":{"type":"string"},"description":"Google Ads customer id, digits only. Defaults to the connection's selected customer."}],"responses":{"200":{"description":"Invitations awaiting approval on the customer","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"approvals":{"type":"array","items":{"$ref":"#/components/schemas/GoogleAdsUserInvitationApproval"}},"cachedAt":{"type":["string","null"],"format":"date-time","description":"When this data was fetched from Google. Null when the cache is unavailable."},"stale":{"type":"boolean","description":"True when Google's quota was exhausted and this is the last successful fetch."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or quota exhausted; retry later."},"501":{"description":"Only available on Google Ads accounts"}}},"delete":{"x-resource-group":"ads","operationId":"withdrawAdAccountUserInvitationApproval","tags":["Ad Accounts"],"x-platforms":["google"],"summary":"Withdraw an invitation awaiting multi-party approval","description":"Cancels an email invitation that Google is still holding for a second admin's approval, so the same address can be invited again right away.\n\nIt resolves the review `multiPartyAuthReviewId` (from POST /v1/ads/accounts/user-invitations or GET on this path) to `REVOKED` through Google's MultiPartyAuthReviewService.\n\nOnly the Google user who sent the invitation can withdraw it, and only while no admin has approved or rejected it. Otherwise Google refuses and this returns a 400.\n\nWithout a withdrawal, Google refuses a new invitation to the address until the review is resolved or expires.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Google ads SocialAccount id."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"Google Ads customer id, digits only."},{"name":"multiPartyAuthReviewId","in":"query","required":true,"schema":{"type":"string"},"description":"Numeric review id from POST /v1/ads/accounts/user-invitations or GET /v1/ads/accounts/user-invitations/pending-approvals."}],"responses":{"200":{"description":"Approval request withdrawn","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"multiPartyAuthReviewId":{"type":"string"},"status":{"type":"string","enum":["REVOKED"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Google Ads operations budget or quota exhausted; retry later."},"501":{"description":"Only available on Google Ads accounts"}}}},"/v1/ads/accounts/users":{"get":{"x-resource-group":"ads","operationId":"listAdAccountUsers","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"Ad account users","description":"Lists the people in a business portfolio assigned to a Meta ad account, with what each can do.\n\nIds are business-scoped user ids (see `GET /v1/ads/businesses/users`).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"Meta ad account id (act_<n>)."},{"name":"businessId","in":"query","required":true,"schema":{"type":"string"},"description":"Business portfolio whose people to list."}],"responses":{"200":{"description":"Assigned users","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"businessId":{"type":"string"},"users":{"type":"array","items":{"$ref":"#/components/schemas/MetaAssignedUser"}}}}}}},"400":{"description":"Invalid input, or Meta rejected the query"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The token lacks business admin access, or the ad account is not selected: grant that access or select the account.","description":"Meta refused: the token lacks business_management or business admin access.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix it, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}},"post":{"x-resource-group":"ads","operationId":"assignAdAccountUser","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"Assign a user to an ad account","description":"Gives a person in your business portfolio access to a Meta ad account, as admin, advertiser, analyst or draft editor.\n\n`MANAGE` is admin, `ADVERTISE`\ncreates and edits ads, `ANALYZE` reads reports, `DRAFT` edits drafts only. Assigning an\nalready assigned user replaces their task set.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","adAccountId","userId","tasks"],"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id used to resolve the Meta token."},"adAccountId":{"type":"string","description":"Meta ad account id (act_<n>)."},"userId":{"type":"string","description":"Business-scoped user id from GET /v1/ads/businesses/users."},"tasks":{"type":"array","minItems":1,"items":{"type":"string","enum":["MANAGE","ADVERTISE","ANALYZE","DRAFT"]}}}},"example":{"accountId":"64b1f0c8a1b2c3d4e5f60718","adAccountId":"act_123456789","userId":"1122334455","tasks":["ADVERTISE","ANALYZE"]}}}},"responses":{"201":{"description":"User assigned","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"user":{"type":"object","properties":{"id":{"type":"string"},"tasks":{"type":"array","items":{"type":"string"}}}}}}}}},"400":{"description":"Invalid input, or Meta rejected the request"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Meta refused the token or the ad account is not selected: grant business access or add the ad account to the selection.","description":"Meta refused: the token lacks business_management or business admin access.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected."},"404":{"description":"Account not found, or Meta could not load the user or ad account."},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}},"delete":{"x-resource-group":"ads","operationId":"removeAdAccountUser","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"Remove a user from an ad account","description":"Removes a person's access to a Meta ad account assigned through your business portfolio.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id used to resolve the Meta token."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"Meta ad account id (act_<n>)."},{"name":"userId","in":"query","required":true,"schema":{"type":"string"},"description":"Business-scoped user id."}],"responses":{"200":{"description":"User removed","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"userId":{"type":"string"},"removed":{"type":"boolean"}}}}}},"400":{"description":"Invalid input, or Meta rejected the request"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Meta refused the token or the ad account is not selected: grant business access or add the ad account to the selection.","description":"Forbidden. One of:\n\n- Meta refused: the token lacks business_management or business admin access.\n- Code `ad_account_not_selected`: the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected."},"404":{"description":"Account not found, or Meta could not load the user or ad account."},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/accounts/finance":{"get":{"x-resource-group":"ads","operationId":"getAdAccountFinance","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"Ad account finances","description":"Shows a Meta ad account's balance, total spend, spend cap and funding source.\n\nFinances of one Meta ad account: prepaid `balance`, lifetime `amountSpent`, account\n`spendCap` (null = no cap) and the `fundingSource`. Money values are converted from\nMeta's minor units to whole units of `currency`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"Meta ad account id (act_<n>)."}],"responses":{"200":{"description":"Account finances","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 code all money values are expressed in."},"balance":{"type":"number","description":"Outstanding/prepaid balance in whole currency units."},"amountSpent":{"type":"number","description":"Lifetime amount spent in whole currency units."},"spendCap":{"type":["number","null"],"description":"Account spend cap; null when none is set."},"fundingSource":{"type":["object","null"],"properties":{"displayString":{"type":"string","description":"Human-readable payment method, e.g. 'Mastercard *4985'."},"type":{"type":"integer","description":"Meta funding source type code."}}}}}}}},"400":{"description":"Invalid input, or Meta rejected the query"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/accounts/health":{"get":{"x-resource-group":"ads","operationId":"getAdAccountHealth","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"Check an ad account before creating ads","description":"Checks whether a Meta ad account can run ads right now, with a fix link for each problem.\n\n### What is checked\n\n- the account status\n- the payment method\n- the account spending limit\n- the Facebook Page and its Instagram account\n- the Page's Lead Ads terms\n- the newest pixel event\n- the WhatsApp number linked to the Page\n- the last refusal Meta gave a create or boost for a reason only the account owner can fix (`last_refusal`, see below)\n\nEach check reads on its own: one this connection cannot see comes back `unknown` instead of failing the request.\n\n### Remembered refusals\n\nMeta cannot be asked about a code 31 security check up front. So `last_refusal` reports the last refusal of this kind that a create or boost met:\n\n- a code 31 security check or a temporary block, remembered for the connection (`accountId`)\n- a payment method, the non-discrimination policy or a disabled account, remembered for the ad account\n\nIt stays until a later create succeeds, or for 7 days (1 day for a temporary block).\n\n### Reading the result\n\n- `ready` is `false` when a create or boost would be refused. `blockers` lists why, each with the `code` a refused create returns (`ad_account_unusable`, `ad_account_payment_required`, `linked_account_required`, `meta_security_check_required`, `ad_account_policy_not_accepted`, ...), a `hint` and a `fix` link.\n- `status` is `blocked` when any check is `error`, `attention` when one is `warning`, else `ok`. It also counts problems that stop delivery but not a create, such as a reached spending limit, so `status` can be `blocked` while `ready` is `true`.\n- A check that is not `ok` carries the `code` of the create refusal it explains, when there is one: `whatsapp` (`missing`) carries `whatsapp_number_not_linked` and `lead_terms` (`missing`) carries `lead_ads_terms_not_accepted`, which only click-to-WhatsApp ads and lead ads hit.\n- `missing` marks an optional asset that is not set up (a pixel, a WhatsApp number): only the ads that need it are affected.\n- An unsettled balance (`account_status` 3) is a `warning`: Meta still accepts creates on it while a payment method is set.\n- A `fix.url` is either a Meta page or a Zernio dashboard path (starting with `/`).\n\n### validateOnly\n\n`POST /v1/ads/create` and `POST /v1/ads/boost` with `validateOnly: true` run the account status and payment checks first. A blocked account answers the same `code` with `details.hint` and `details.fix`, without a Meta dry run (Meta counts dry runs as ad writes).\n\nThey read the account state cached for up to 5 minutes. This endpoint always reads it fresh and refreshes that cache.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string","example":"act_123"},"description":"Meta ad account id (act_<n>)."}],"responses":{"200":{"description":"Account checks","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"status":{"type":"string","enum":["ok","attention","blocked"]},"ready":{"type":"boolean","description":"False when a create or boost on this ad account would be refused; `blockers` says why."},"blockers":{"type":"array","items":{"type":"object","required":["check","code","message","hint"],"properties":{"check":{"type":"string","description":"The `checks[].id` that blocks."},"code":{"type":"string","example":"ad_account_payment_required","description":"The error code a refused create or boost returns for this reason."},"message":{"type":"string"},"hint":{"type":"string","description":"What to do, in English."},"fix":{"type":"object","properties":{"label":{"type":"string"},"url":{"type":"string"}}}}}},"checkedAt":{"type":"string","format":"date-time"},"checks":{"type":"array","items":{"type":"object","required":["id","status","title","message"],"properties":{"id":{"type":"string","enum":["account_status","payment","spend_cap","page","instagram","lead_terms","pixel","whatsapp","last_refusal"]},"status":{"type":"string","enum":["ok","warning","error","missing","unknown"]},"title":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"When the check is not `ok`: the error code a create refused for this reason returns."},"hint":{"type":"string"},"fix":{"type":"object","properties":{"label":{"type":"string"},"url":{"type":"string"}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/accounts/live":{"get":{"x-resource-group":"ads","operationId":"getAdAccountLiveEntities","tags":["Ad Accounts"],"x-platforms":["meta","tiktok"],"summary":"Read an ad account's campaigns and ad sets live","description":"Reads an ad account's campaigns and ad sets straight from Meta or TikTok, so checks like budget limits see current values.\n\nIt reads one Meta ad account or TikTok advertiser **live from the platform**, so it is cheap enough to run before every write. For example, a per-ad-account spend ceiling that must see the current daily / lifetime budget rather than the synced copy.\n\n- Meta: a single Graph call per request (the account's `/campaigns` and `/adsets` edges, filtered by `effective_status`).\n- TikTok: one `campaign/get` and one `adgroup/get` page (TikTok ad groups are returned as `adSets`).\n\nOther platforms answer 501 rather than serving synced data.\n\n### Live vs synced\n\nGET /v1/ads/campaigns and GET /v1/ads/ad-sets serve Zernio's synced store, refreshed by background sync (typically 15 to 60 minutes behind Meta). Their `live=true` re-reads only the on/off switches of at most 20 objects.\n\nThis endpoint returns what Meta reports at `readAt`, for every matching campaign and ad set, and stores nothing.\n\n### Budgets\n\nBudgets and bid amounts are in whole units of `currency`, the same units as the synced rows (Meta's minor units are converted; TikTok already reports whole units).\n\nA campaign with a campaign budget (Meta Advantage+ campaign budget, TikTok campaign budget optimization) carries `budget`; otherwise each ad set carries its own.\n\n### Paging\n\nEach level returns at most `limit` rows. When more match, `paging.<level>.after` is a cursor: pass it back as `after` together with `level` to read the next page of that level only.\n\nTikTok pages by number, so a TikTok cursor must be sent with the same `limit` that produced it (another `limit` is a 400).\n\n### TikTok specifics\n\n`status` maps to TikTok's `primary_status` filter, which takes one value:\n\n- ACTIVE = delivering (`STATUS_DELIVERY_OK`)\n- PAUSED = switched off (`STATUS_DISABLE`)\n- DELETED = `STATUS_DELETE`\n- omitted = every status except deleted (`STATUS_NOT_DELETE`, which includes enabled entities that are not delivering, such as an ad group in review)\n\nSeveral values, or IN_PROCESS, WITH_ISSUES, CAMPAIGN_PAUSED and ARCHIVED, are a 400.\n\nResponse fields on TikTok:\n\n- `budgetRemaining` and `spendCap` are always null (TikTok reports neither).\n- Campaign `bidStrategy` is null (TikTok bids per ad group).\n- Ad set `bidStrategy` is normalized to the Meta vocabulary like GET /v1/ads.\n- `promotedObject` is `{ pixelId, customEventType, applicationId, customConversionId }` (the keys TikTok has set, as POST /v1/ads/create takes them).\n- `targeting` holds TikTok's targeting fields verbatim.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the platform token."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"Meta ad account id (act_<n>) or TikTok advertiser id (digits)."},{"name":"status","in":"query","required":false,"schema":{"type":"string","example":"ACTIVE"},"description":"Comma-separated Meta `effective_status` values to keep: ACTIVE, PAUSED, IN_PROCESS,\nWITH_ISSUES, DELETED, ARCHIVED, and CAMPAIGN_PAUSED (ad sets only; the campaigns level\nignores it). Defaults to every status except DELETED and ARCHIVED. An unknown value is a 400.\nTikTok takes a single value: ACTIVE, PAUSED or DELETED (see the description)."},{"name":"level","in":"query","required":false,"schema":{"type":"string","enum":["campaign","adSet"]},"description":"Read only one level. Required with `after`. Both levels are read when omitted."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":200},"description":"Maximum rows per level in this response."},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor from `paging.campaigns.after` or `paging.adSets.after` of a previous response. Requires `level` (and on TikTok the same `limit`)."}],"responses":{"200":{"description":"Live campaigns and ad sets","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"},"adAccountId":{"type":"string"},"platform":{"type":"string","enum":["facebook","tiktok"]},"currency":{"type":"string","description":"ISO 4217 code every budget and bid amount is expressed in."},"readAt":{"type":"string","format":"date-time","description":"When the platform was read."},"campaigns":{"type":"array","description":"Absent when `level=adSet`.","items":{"type":"object","properties":{"platformCampaignId":{"type":"string"},"campaignName":{"type":["string","null"]},"platformCampaignStatus":{"type":["string","null"],"description":"Meta `effective_status` (ACTIVE, PAUSED, WITH_ISSUES...) or TikTok `secondary_status` (CAMPAIGN_STATUS_ENABLE...)."},"configuredStatus":{"type":["string","null"],"description":"The campaign's own switch: Meta `status` (ACTIVE, PAUSED, DELETED, ARCHIVED), or TikTok `operation_status` as ACTIVE (ENABLE) / PAUSED (DISABLE)."},"status":{"type":"string","description":"Zernio's normalized status (active, paused, ...), derived from `platformCampaignStatus`."},"budget":{"type":["object","null"],"description":"The campaign budget, same shape as the synced rows. Null when the budget lives on the ad sets.","properties":{"amount":{"type":"number"},"type":{"type":"string","enum":["daily","lifetime"]}}},"dailyBudget":{"type":["number","null"],"description":"Daily budget in whole units of `currency` (Meta `daily_budget`; TikTok `budget` under a daily budget mode)."},"lifetimeBudget":{"type":["number","null"],"description":"Lifetime budget in whole units of `currency` (Meta `lifetime_budget`; TikTok `budget` under BUDGET_MODE_TOTAL)."},"budgetMode":{"type":["string","null"],"description":"TikTok only: `budget_mode` as TikTok reports it (BUDGET_MODE_DAY, BUDGET_MODE_DYNAMIC_DAILY_BUDGET, BUDGET_MODE_TOTAL, BUDGET_MODE_INFINITE)."},"budgetRemaining":{"type":["number","null"],"description":"Meta `budget_remaining` in whole units of `currency`. Null when the campaign has no budget of its own, and always on TikTok."},"spendCap":{"type":["number","null"],"description":"Campaign spending limit (Meta `spend_cap`) in whole units of `currency`. Null when none is set, and always on TikTok."},"bidStrategy":{"type":["string","null"],"description":"Meta `bid_strategy`, set on campaigns with a campaign budget. Null on TikTok."}}}},"adSets":{"type":"array","description":"Absent when `level=campaign`.","items":{"type":"object","properties":{"platformAdSetId":{"type":"string"},"adSetName":{"type":["string","null"]},"platformCampaignId":{"type":["string","null"]},"platformAdSetStatus":{"type":["string","null"],"description":"Meta `effective_status` (ACTIVE, PAUSED, CAMPAIGN_PAUSED...) or TikTok `secondary_status` (ADGROUP_STATUS_DELIVERY_OK, ADGROUP_STATUS_AUDIT...)."},"configuredStatus":{"type":["string","null"],"description":"The ad set's own switch: Meta `status`, or TikTok `operation_status` as ACTIVE / PAUSED."},"status":{"type":"string","description":"Zernio's normalized status, derived from `platformAdSetStatus`."},"budget":{"type":["object","null"],"description":"The ad set budget, same shape as the synced rows. Null under a campaign budget.","properties":{"amount":{"type":"number"},"type":{"type":"string","enum":["daily","lifetime"]}}},"dailyBudget":{"type":["number","null"],"description":"Daily budget in whole units of `currency`."},"lifetimeBudget":{"type":["number","null"],"description":"Lifetime budget in whole units of `currency`."},"budgetMode":{"type":["string","null"],"description":"TikTok only: `budget_mode` as TikTok reports it."},"budgetRemaining":{"type":["number","null"],"description":"Meta `budget_remaining` in whole units of `currency`. Null when the ad set has no budget of its own, and always on TikTok."},"bidStrategy":{"type":["string","null"],"description":"Meta `bid_strategy`. On TikTok the ad group's `bid_type` normalized to the same vocabulary (LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, LOWEST_COST_WITH_MIN_ROAS)."},"bidAmount":{"type":["number","null"],"description":"Bid cap or cost target in whole units of `currency` (Meta `bid_amount`; TikTok `bid_price`, else `conversion_bid_price`, else `deep_cpa_bid`). Null when the strategy has none."},"optimizationGoal":{"type":["string","null"],"description":"Meta or TikTok `optimization_goal`."},"billingEvent":{"type":["string","null"],"description":"Meta or TikTok `billing_event`."},"promotedObject":{"type":["object","null"],"additionalProperties":true,"description":"Meta `promoted_object` verbatim (snake_case). On TikTok `{ pixelId, customEventType, applicationId, customConversionId }` from `pixel_id`, `optimization_event`, `app_id` and `custom_conversion_id`, only the keys TikTok has set; null when none is."},"targeting":{"type":["object","null"],"additionalProperties":true,"description":"The platform's targeting verbatim (snake_case), as it reports it now: Meta `targeting`, or TikTok's ad group targeting fields (location_ids, age_groups, gender, languages, interest_category_ids, audience_ids, placements...)."},"schedule":{"type":["object","null"],"properties":{"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time","description":"Absent when the ad set runs until it is stopped."}}},"adSchedule":{"description":"Meta only. The ad set's dayparting (`adset_schedule`) in the `platformSpecificData.adSchedule` shape, one window per day (a window Meta stores off the hour is widened to whole hours). Null when the ad set runs around the clock. Absent on TikTok.","oneOf":[{"$ref":"#/components/schemas/MetaAdSchedule"},{"type":"null"}]}}}},"paging":{"type":"object","description":"One entry per level read. `after` is null on the last page.","properties":{"campaigns":{"type":"object","properties":{"after":{"type":["string","null"]}}},"adSets":{"type":"object","properties":{"after":{"type":["string","null"]}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads access required (Ads add-on on legacy plans, included on usage-based plans)."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"Platform rate limit reached; retry later (after the indicated delay on Meta)."},"501":{"x-summary":"This platform has no bulk live read: use the synced campaigns and ad sets endpoints instead.","description":"The platform has no bulk live read (Meta and TikTok today). Use the synced GET /v1/ads/campaigns and GET /v1/ads/ad-sets there."},"502":{"description":"The platform did not return the ad account or its currency (for example a deleted ad account)."}}}},"/v1/ads/accounts":{"post":{"x-resource-group":"ads","operationId":"createAdAccount","summary":"Create ad account","tags":["Ad Accounts"],"x-platforms":["meta","google"],"description":"Creates a new Meta ad account in the user's own business portfolio, or a Google Ads client account under a manager (MCC) account the connection reaches. Billing must then be set up on the platform.\n\n**Meta** (omit `platform` or send `meta`).\n\nCreates a durable Meta ad account in the end user's own business portfolio using their connected Meta Ads token.\n\n### Meta requirements\n\n- An active metaads accountId\n- Ads access\n- business_management permission\n- Business admin access\n\nDiscover portfolios with GET /v1/ads/businesses. System-user tokens may return an empty businesses list; supply the known business ID in that case.\n\n### Meta billing and limits\n\nThe self-serve account starts without a payment method. The user must add a payment method in Ads Manager before ads can deliver. Zernio cannot add payment methods.\n\nMeta may require business verification and limits how many accounts a business can create. Closing an account does not guarantee more capacity. An ad account cannot truly be deleted, even after closing it and removing it from a business.\n\n### Meta fields\n\n- timezoneId is Meta's numeric ID, not an IANA timezone name. Select it from https://developers.facebook.com/docs/marketing-api/reference/ad-account/timezone-ids/. For example, 1 is America/Los_Angeles.\n- Meta validates supported currencies and IDs.\n- endAdvertiser, mediaAgency and partner default to NONE for the self-serve flow.\n\n### Meta connection scope\n\nThe new account is added atomically to an existing scoped ad-account allowlist. Unrestricted connections stay unrestricted. Reconnecting the same Meta identity preserves this scope unless a caller explicitly replaces it.\n\nDiscovery is nudged immediately. Use the returned adAccountId with the existing ads endpoints.\n\n### Meta retries and failures\n\nThis operation is not idempotent and Zernio never automatically retries it. Unknown body fields are rejected. The Meta flow has no validateOnly or dry-run option.\n\n- After a timeout or a 502 with details.creationStatus=unknown, check the business in Ads Manager before attempting another creation.\n- A 201 with connectionUpdated=false means the account exists but needs reconnecting via GET /v1/connect/facebook/ads, with adAccountIds containing the returned ID and the previous scoped IDs. Do not repeat the create call.\n\n**Google** (send `platform: google`).\n\nGoogle only creates accounts through a manager account. The new client account is created under `managerCustomerId`, which must be a manager the Google user behind the googleads `accountId` reaches (directly or as a sub-manager). List them with GET /v1/ads/accounts/hierarchy.\n\nWhose manager it is (the integrator's or the end user's) is the caller's choice: pass the connection that reaches it.\n\n### Google fields and limits\n\n- `currency` (ISO 4217) and `timeZone` (IANA name, for example Europe/Madrid) cannot be changed after creation.\n- The account starts without billing: set it up in Google Ads before ads can serve.\n- Google caps how many accounts a manager can create and how many active client accounts it can hold.\n\n### Google result and retries\n\nThe new customer is added to the connection (and to a scoped connection's allowlist). Discovery is nudged immediately, and the returned adAccountId works with every other ads endpoint.\n\n`validateOnly: true` asks Google to validate the request without creating anything and returns 200.\n\nA real create is not idempotent: after a 502 with details.creationStatus=unknown, check the manager in Google Ads before trying again.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CreateMetaAdAccountRequest"},{"$ref":"#/components/schemas/CreateGoogleAdAccountRequest"}]},"examples":{"meta":{"summary":"Meta ad account in a business portfolio","value":{"accountId":"69fc524892b3d8e85f893e73","businessId":"123456789012345","name":"Customer advertising","currency":"EUR","timezoneId":1}},"google":{"summary":"Google Ads client account under a manager","value":{"platform":"google","accountId":"69fc524892b3d8e85f893e73","managerCustomerId":"4234071052","name":"Customer advertising","currency":"EUR","timeZone":"Europe/Madrid"}}}}}},"responses":{"200":{"x-summary":"Google accepted the validation-only request and nothing was created.","description":"Google validateOnly request accepted by Google. Nothing was created.","content":{"application/json":{"schema":{"type":"object","required":["platform","managerCustomerId","validateOnly"],"properties":{"platform":{"type":"string","enum":["google"]},"managerCustomerId":{"type":"string"},"validateOnly":{"type":"boolean","description":"Always true on a 200."}}}}}},"201":{"x-summary":"The ad account was created: check `connectionUpdated` and the returned billing instructions.","description":"Ad account created. Check connectionUpdated and the billing instructions.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CreatedMetaAdAccount"},{"$ref":"#/components/schemas/CreatedGoogleAdAccount"}]},"examples":{"meta":{"value":{"adAccountId":"act_123456789012345","businessId":"123456789012345","connectionUpdated":true,"paymentMethodRequired":true,"adsManagerUrl":"https://adsmanager.facebook.com/adsmanager/manage/accounts?act=123456789012345","nextSteps":"The user must configure payment in Meta Ads Manager before ads can deliver. Add a payment method there, or confirm an existing funding or invoicing arrangement. Zernio cannot add payment methods through the API.","warnings":[]}},"google":{"value":{"platform":"google","adAccountId":"5551234567","managerCustomerId":"4234071052","connectionUpdated":true,"warnings":[],"paymentMethodRequired":true,"nextSteps":"The account has no billing yet. If the manager has monthly invoicing, set it up with POST /v1/ads/accounts/billing; otherwise add billing in Google Ads (Billing > Settings). Ads do not serve until billing is set up. Zernio cannot add payment methods through the API.","validateOnly":false}}}}}},"400":{"x-summary":"The input is invalid, the manager customer is unreachable, or the platform rejected creation: fix the request using the error details.","description":"Invalid input, a managerCustomerId the connection does not reach, or a Meta or Google rejection. For Meta, details.reason identifies creation_limit, business_verification_required, unsupported_currency, unsupported_timezone or business_unavailable when recognized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"This business has reached its Meta ad account creation limit. Use an existing ad account or ask Meta Business Support about increasing the limit. Closing accounts does not guarantee additional capacity.","code":"invalid_field_value","type":"invalid_request_error","param":"businessId","platform":"meta","details":{"reason":"creation_limit"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is denied or the platform permission is missing: grant the required permission on the connection and retry.","description":"Ads access denied, Meta permission missing (details.reason may be business_management_required, business_admin_required or business_access_required), or Google denied the connection's user permission on managerCustomerId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"x-summary":"Google Ads rate limit or quota was reached before creation: retry later.","description":"Google Ads rate limit or quota reached before the account was created. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"501":{"description":"platform google was sent with an accountId that is not a googleads connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"x-summary":"The creation outcome is unknown: check the ad platform for the account before repeating this non-idempotent request.","description":"Creation outcome unknown (details.creationStatus=unknown). Check Ads Manager or the Google Ads manager account before repeating this non-idempotent request. A Google validateOnly request answers 502 without creationStatus when Google did not respond; that is safe to retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Meta did not confirm whether the ad account was created. Do not repeat this request until you check the business portfolio in Ads Manager.","code":"platform_api_error","type":"platform_error","platform":"meta","details":{"creationStatus":"unknown"}}}}}}},"get":{"x-resource-group":"ads","operationId":"listAdAccounts","tags":["Ad Accounts"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit","microsoft"],"summary":"List ad accounts","description":"Lists the ad accounts a connection can manage, such as Meta ad accounts, TikTok advertisers or Google Ads customers.\n\nReturns the platform ad accounts available for the given account (e.g. Meta ad accounts, TikTok advertiser IDs, Google Ads customer IDs).\n\n### Meta\n\nMeta business-login accounts use their own system-user token.\n\nFresh Meta discovery includes businessId and businessName from the owning Business Manager when available. Cached entries gain these fields after the next discovery refresh.\n\n### TikTok agencies\n\n1. Zernio enumerates every advertiser under every Business Center the token can read (paginated server-side).\n2. It then chunks the lookup against TikTok's `/advertiser/info/` endpoint (which has a per-call cap of ≤100 IDs).\n\nSolo advertisers without a BC fall back to the OAuth-time `advertiser_ids` list. The result is cached for 1h on the SocialAccount and lazy-refreshed on first call after expiry.\n\n### Google Ads\n\nResponds `429` when Google's API quota is temporarily exhausted (instead of an empty list). Retry after a delay.\n\n### Reddit Ads (`redditads`)\n\nEvery Reddit ad account the connected Reddit user can reach, with `businessId`, `approvalStatus` (Reddit's `admin_approval`), `timezone` and `type`.\n\n### Selection (`selected`)\n\nEvery listed ad account carries `selected`: whether it is in the connection's ad-account selection. That is the ad accounts picked at connect time or in the dashboard picker, the ones Zernio syncs. On a connection without a selection every ad account is `selected: true`.\n\nWrites through /v1/ads endpoints to an ad account with `selected: false` answer `403 ad_account_not_selected`. Add it to the selection first (dashboard picker, or `GET /v1/connect/{platform}/ads` with `adAccountIds`).\n\nThe list includes unselected ad accounts by default. Pass `inScopeOnly=true` to get only the ones this connection can use.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Account ID"},{"name":"adAccountId","in":"query","required":false,"schema":{"type":"string"},"description":"Filter response to a single platform ad account ID (e.g. `act_123` for Meta, advertiser_id for TikTok). Returns at most one item."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Clamp the returned `accounts[]` length. Useful for typeahead pickers on agency tokens with hundreds of advertisers."},{"name":"inScopeOnly","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"`true` returns only the ad accounts this connection accepts as `adAccountId` on the other /v1/ads endpoints, i.e. those inside its ad-account selection (every item then has `selected: true`). Without it, every ad account the login can reach is listed and `selected` flags selection membership.\n\n- Meta, LinkedIn, X and Reddit: drops the ad accounts with `selected: false`; a connection without a selection keeps them all.\n- Google Ads: also drops customers the login reaches that are not on this connection (for example ones selected on another connection of the same login), which those endpoints answer with a 400.\n- TikTok and Pinterest: no selection, so the list is unchanged."}],"responses":{"200":{"description":"Ad accounts","content":{"application/json":{"schema":{"type":"object","properties":{"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Platform ad account ID (e.g. act_123)"},"name":{"type":"string"},"currency":{"type":"string"},"businessId":{"type":"string","description":"Meta only. Owning Business Manager ID when available on the grant."},"businessName":{"type":"string","description":"Owning business name when supplied by the platform."},"status":{"type":"string","description":"LinkedIn only. LinkedIn's own ad account status. In practice always `ACTIVE`, because the LinkedIn query filters to active accounts. Meta, Google, TikTok and Pinterest report `accountStatus` instead; X reports `approvalStatus`."},"accountStatus":{"description":"The platform's own account status, forwarded unchanged. No JSON type is declared because it differs per platform: Meta sends an integer; Google, TikTok and Pinterest send a string. Absent on LinkedIn (reports `status`) and X (reports `approvalStatus`).\n\nTo know only whether the account can run ads now, read `selectable` instead. Read this field to tell the states apart, since they need different responses:\n\n- `1` ACTIVE: running normally.\n- `2` DISABLED: disabled by Meta. Read `disableReason` to tell a policy action from a billing one; they need very different follow-ups.\n- `3` UNSETTLED: unpaid balance, but the account still runs ads. Not a ban.\n- `7` PENDING_RISK_REVIEW: Meta is reviewing the account. Wait for the outcome.\n- `8` PENDING_SETTLEMENT: Meta blocks new ads until an outstanding balance clears. Settle it and the account runs again.\n- `9` IN_GRACE_PERIOD: still running, on a deadline.\n- `100` PENDING_CLOSURE: scheduled to close.\n- `101` CLOSED: terminal.\n"},"approvalStatus":{"type":"string","description":"X and Reddit only. X's own ad account approval status, or Reddit's `admin_approval`. Observed X values are `ACCEPTED`, `PENDING` and `REJECTED`, but X does not publish the full vocabulary, so treat an unrecognised value as not usable. Other platforms report `accountStatus` or `status` instead."},"timezone":{"type":"string","description":"Reddit only. The ad account's time zone as Reddit reports it (`time_zone_id`). Schedules on Reddit ads are read in this zone."},"type":{"type":"string","description":"Reddit only. Reddit's ad account type, forwarded unchanged."},"disableReason":{"type":"integer","description":"Meta only. Meta's `disable_reason` code, forwarded unchanged.\n\nPresent when `accountStatus` is `2` (DISABLED) and Meta gives a reason; this separates a policy action from a payment problem. Absent when Meta reports no reason, or the connected token cannot read the field.\n\nMeta publishes no stable list of values, so none are enumerated here: resolve the code against Meta's own ad account reference."},"balance":{"type":"number","description":"TikTok only. Total balance the advertiser can spend (cash plus grant), in whole units of `currency`.\n\nRead from the Business Center balance when the connection has a finance role there: the only TikTok source that counts cash held in a shared payment portfolio. Otherwise TikTok's advertiser-level balance, which can read 0 for a cash-funded advertiser."},"cashBalance":{"type":"number","description":"TikTok only. Cash part of `balance`, in whole units of `currency`. Absent when the connection has no finance role in the advertiser's Business Center."},"grantBalance":{"type":"number","description":"TikTok only. Grant (ad credit) part of `balance`, in whole units of `currency`. Absent when the connection has no finance role in the advertiser's Business Center."},"timezoneName":{"type":"string","description":"IANA timezone of the ad account (Meta only). Drives daily-budget reset and Insights day boundaries."},"timezoneOffsetHoursUtc":{"type":"number","description":"Signed UTC offset in hours, reflecting current DST (Meta only)."},"minimumDailyBudget":{"type":"number","description":"Meta only. Minimum daily budget for the account, in the account currency's major units. This is the impressions-billed minimum; other billing events have higher minimums. Absent when the connected token cannot read it."},"fundingSource":{"type":"string","description":"Meta only. Meta's `funding_source` ID for the ad account, forwarded unchanged. ABSENT when this connection's token cannot see billing, when the account has no payment method, and for accounts paid through Business Billing Hub, which still create ads. Absence alone is not a missing payment method."},"fundingSourceDetails":{"type":"object","description":"Meta only. Meta's `funding_source_details` object, forwarded unchanged.\nABSENT under exactly the same conditions as `fundingSource`, never sent\nas null or as an empty object. Read `billingStatus` for what the\nabsence means.\n","properties":{"id":{"type":"string","description":"Meta's ID for the funding instrument. Matches `fundingSource`."},"displayString":{"type":"string","description":"Meta's own human-readable label for the funding instrument, e.g. 'Available Balance (EUR)' or a masked card. Meta composes this string; do not parse it."},"type":{"type":"integer","description":"Meta's raw numeric funding-source type, forwarded unchanged. Meta publishes no mapping from these numbers to payment-method kinds, so none is documented here and none should be inferred."}}},"billingStatus":{"type":"string","enum":["ok","missing","unknown"],"description":"Meta only. Whether the ad account has a payment method:\n\n- `missing`: `accountStatus` is `3` (UNSETTLED) or `9` (IN_GRACE_PERIOD), or `disableReason` is `3` (RISK_PAYMENT).\n- `missing`, effect: ad creation fails at the ad step with Meta code 100 / subcode 1359188. Add a payment method in Meta's Billing & payments center.\n- `ok`: Meta returns a funding source. This is presence, not validity: Meta can still refuse the card or balance at ad creation.\n- `unknown`: Meta returns no funding source. The token may not see billing, the account may have no payment method, or it is paid through Business Billing Hub (Meta omits the funding source there even for admins). Meta decides at ad creation.\n"},"selectable":{"type":"boolean","description":"Meta and X only. Whether the account can create/run ads now. Always present on every Meta and X account. Absent (treat as true) on other platforms."},"unusableReason":{"type":["string","null"],"description":"Meta and X only. Always present on every Meta and X account. Human-readable reason when selectable is false; null when selectable."},"selected":{"type":"boolean","description":"Always present. True when the ad account is in this connection's ad-account selection, or when the connection has no selection (then every ad account is usable).\n\n- For a posting account (e.g. facebook, twitter), the selection of its ads connection applies.\n- Unrelated to `selectable`, which is the platform's own status.\n- Writes to an ad account with `selected: false` answer 403 `ad_account_not_selected`.\n- `inScopeOnly=true` lists only the selected ones."}}}},"cachedAt":{"type":["string","null"],"format":"date-time","description":"Google only. When this list was fetched from Google. Null when it was never served from cache. Absent on other platforms."},"stale":{"type":"boolean","description":"Google only. True when Google's daily API quota was exhausted and this is the last successful fetch, not a live read. Absent on other platforms."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"description":"Platform ads connection required (TikTok Ads, X Ads) or Instagram missing linked Facebook account"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"x-resource-group":"ads","operationId":"updateAdAccount","tags":["Ad Accounts"],"x-platforms":["meta","google"],"summary":"Update ad account settings","description":"Changes a Meta ad account's name, spend cap or default EU DSA beneficiary and payor.\n\nPass any combination of fields. On Google Ads, only URL tracking fields apply (see below). Other platforms return 400.\n\n### Spend cap\n\n`spendCap` is the total the account may spend before Meta pauses every campaign in it, in whole units of the account currency.\n\n- `spendCap: null` removes the cap.\n- `resetAmountSpent: true` restarts the amount counted against it from zero.\n\nWhen `name`, `spendCap` or `resetAmountSpent` is passed, the response carries `settings`: the account's finances re-read after the write (same shape as `GET /v1/ads/accounts/finance`). The effective cap can be confirmed in one call.\n\n### DSA defaults\n\nSets the default DSA beneficiary and payor on the ad account (EU DSA, Article 26). Set them once and every EU-targeted call to `/v1/ads/create`, `/v1/ads/boost` and `/v1/ads/ctwa` on that ad account can omit `dsaBeneficiary`/`dsaPayor`: Meta applies the defaults automatically.\n\nThe values are written to the ad account on Meta, the same setting Ads Manager edits. Nothing is stored in Zernio, and defaults already set in Ads Manager work identically.\n\nZernio never guesses these values for you. Beneficiary and payor are legal disclosures shown to EU users, so you must provide the entity names explicitly. Use `GET /v1/ads/dsa-recommendations` to offer suggestions in your UI.\n\nIf `defaultDsaPayor` is omitted, the beneficiary is also set as the payor. That covers the common case where the same entity benefits from and pays for the ads. Read the current values back with `GET /v1/ads/dsa-defaults`.\n\n### Google: account-level URL tracking\n\nOn a Google Ads connection, `adAccountId` is the customer id and only `trackingUrlTemplate` / `finalUrlSuffix` are accepted (the Meta fields return 400).\n\n- They write `customer.tracking_url_template` and `customer.final_url_suffix`, one update mask leaf per field sent.\n- An empty string clears the field.\n- The response carries `urlTracking` with the values written.\n\nFor one campaign, send the same fields to PUT /v1/ads/campaigns/{campaignId}.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","adAccountId"],"properties":{"accountId":{"type":"string","description":"Account ID (metaads, or a facebook/instagram posting account)"},"adAccountId":{"type":"string","description":"Meta ad account ID (act_...)"},"name":{"type":"string","maxLength":255,"description":"New ad account name."},"spendCap":{"type":["number","null"],"description":"Account spend cap in whole currency units; null removes it."},"resetAmountSpent":{"type":"boolean","description":"Restart the amount counted against the cap from zero. Cannot be combined with spendCap null."},"defaultDsaBeneficiary":{"type":"string","maxLength":100,"description":"Legal entity benefiting from ads on this ad account"},"defaultDsaPayor":{"type":"string","maxLength":100,"description":"Legal entity paying for ads on this ad account. Defaults to defaultDsaBeneficiary when omitted. Requires defaultDsaBeneficiary."},"trackingUrlTemplate":{"type":"string","description":"**Google only.** Account tracking template (customer.tracking_url_template); an empty string clears it."},"finalUrlSuffix":{"type":"string","description":"**Google only.** Account final URL suffix (customer.final_url_suffix); an empty string clears it."}}},"example":{"accountId":"64b1f0c8a1b2c3d4e5f60718","adAccountId":"act_123456789","spendCap":500}}}},"responses":{"200":{"description":"Settings updated (each block re-read from Meta after the write)","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"urlTracking":{"type":"object","description":"Google only. The URL tracking fields written.","properties":{"trackingUrlTemplate":{"type":"string"},"finalUrlSuffix":{"type":"string"}}},"dsaDefaults":{"type":"object","description":"Present when defaultDsaBeneficiary was passed.","properties":{"beneficiary":{"type":"string"},"payor":{"type":"string"}}},"settings":{"type":"object","description":"Present when name, spendCap or resetAmountSpent was passed.","properties":{"name":{"type":"string"},"currency":{"type":"string"},"balance":{"type":"number"},"amountSpent":{"type":"number"},"spendCap":{"type":["number","null"]},"fundingSource":{"type":["object","null"],"properties":{"displayString":{"type":"string"},"type":{"type":"integer"}}}}}}}}}},"400":{"description":"Unsupported platform (non-Meta account), invalid adAccountId, or Meta rejected the update"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Meta refused the token or the ad account is not selected: grant access or add the ad account to the selection.","description":"Meta refused: the token cannot manage this ad account.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection), or use a connection that has it selected."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/ads/dsa-defaults":{"get":{"x-resource-group":"ads","operationId":"getDsaDefaults","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"Get ad account DSA defaults","description":"Shows the default EU DSA beneficiary and payor set on a Meta ad account.\n\nReturns the default DSA beneficiary and payor currently set on a Meta ad account,\nwhether they were set via `PATCH /v1/ads/accounts` or in Meta Ads Manager. Fields\nare omitted when no default is configured. Meta accounts only.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Account ID (metaads, or a facebook/instagram posting account)"},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"Meta ad account ID (act_...)"}],"responses":{"200":{"description":"Current DSA defaults (empty object when none are set)","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"dsaDefaults":{"type":"object","properties":{"beneficiary":{"type":"string"},"payor":{"type":"string"}}}}}}}},"400":{"description":"Non-Meta adAccountId"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/ads/dsa-recommendations":{"get":{"x-resource-group":"ads","operationId":"getDsaRecommendations","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"Get DSA recommendations","description":"Suggests beneficiary and payor names for a Meta ad account's EU DSA disclosures, for your user to pick from.\n\nReturns Meta's suggested beneficiary/payor names for an ad account, derived by Meta\nfrom the account's recent activity. Useful for prefilling `dsaBeneficiary`/`dsaPayor`\ninputs, or the defaults sent to `PATCH /v1/ads/accounts`, in your own UI.\n\nMeta returns a single flat list. Entries are not labeled as beneficiary or payor,\nand since these are legal disclosures Zernio never applies them automatically: let\nyour user pick the right entity. The list may be empty for accounts with little\nactivity. Meta accounts only.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Account ID (metaads, or a facebook/instagram posting account)"},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"Meta ad account ID (act_...)"}],"responses":{"200":{"description":"Suggested DSA strings (may be empty when Meta has no recommendations)","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"recommendations":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Non-Meta adAccountId"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/ads/boost":{"post":{"x-resource-group":"ads","operationId":"boostPost","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"Boost post as ad","description":"Turns an already published post into a paid ad that keeps the post's likes and comments, creating the campaign around it.\n\nBy default it provisions the whole hierarchy (campaign, ad set, ad).\n\n### Attach shape (Meta)\n\nSend `adSetId` to put the ad under an EXISTING ad set instead, so that ad set keeps its learning phase.\n\nThat ad set then owns `budget`, `schedule` and `targeting`. Sending any of those alongside `adSetId` is a 400 rather than a silent drop. `budget` is required only without `adSetId`.\n\n`instagramAccountId`, `destinationType`, `whatsappPhoneNumber` and `adSetId` are Meta-only and return 400 on other platforms.\n\n### Meta accounts\n\n`accountId` may be a Facebook, Instagram or Meta ads (business login) connection.\n\nA business-login connection has no posting account, so pass the post as `platformPostId` (Facebook `pageId_postId` or an Instagram media id). A Zernio `postId` is a 400 there.\n\n### X\n\n`accountId` may be the posting X account or its X Ads connection: either resolves the other on the same profile.\n\nA Zernio `postId` on an X Ads connection resolves through its X account, and is a 400 when the profile has none (pass `platformPostId` instead).\n\n### Reddit\n\n`accountId` is the Reddit Ads connection (platform `redditads`). Pass the Reddit post as either:\n\n- `platformPostId` (`t3_abc123` or the bare id)\n- a Zernio `postId`, which resolves through the Reddit account connected on the same profile (400 when there is none)\n\nReddit promotes only posts made by a profile of the ad account: a post by any other author returns 422.\n\nGoals:\n\n- traffic\n- awareness\n- conversions\n- video_views (the post must be a video, 422 otherwise)\n- lead_generation\n\nconversions and lead_generation need a pixel that already received the event (see `promotedObject`).\n\n`leadGenFormId` returns 400: Reddit retired its native lead forms, so `lead_generation` sends people to `linkUrl` and optimizes toward the pixel's Lead event.\n\nEach boost creates a campaign, an ad group carrying the budget, the targeting and the bid, and the ad. `bidStrategy` sets the ad group's bid:\n\n- LOWEST_COST_WITHOUT_CAP (or omitted): automatic bidding (BIDLESS)\n- LOWEST_COST_WITH_BID_CAP: MANUAL_BIDDING with `bidAmount` as the bid\n- COST_CAP: MAXIMIZE_VOLUME with `bidAmount` as the cap\n- Any other strategy returns 422 before anything is created.\n\n### Messaging boosts (Meta)\n\nUse `goal: engagement` with one of these CTAs:\n\n- `callToAction: WHATSAPP_MESSAGE`: implies WHATSAPP\n- `MESSAGE_PAGE`: implies MESSENGER\n- `INSTAGRAM_MESSAGE`: implies INSTAGRAM_DIRECT\n\n`destinationType` alone does not select a messaging CTA. Omit `linkUrl` only for messaging CTAs. Plain link CTAs keep their goal and link behavior when combined with an independent `destinationType`.\n\nThe campaign uses OUTCOME_ENGAGEMENT and the ad set uses CONVERSATIONS with the promoted Page. Optional `whatsappPhoneNumber` selects a number already paired with that Page.\n\nConflicting CTA/destination, instant form, goal, or optimizationGoal inputs return 400. Attach requires the target ad set destination to match.\n\nExisting post references preserve social proof. An Instagram reel rejected by Meta is not re-uploaded as a new post for a messaging boost.\n\n### Retries\n\nBoosts are NOT idempotent and can take minutes when Meta requires re-hosting an Instagram video, so do not retry on client timeout.\n\nSend an Idempotency-Key header to make retries safe: same key and body replays the original 201, and distinct keys always create distinct ads.\n\nWithout the header, an identical request is treated as a retry:\n\n- While one is in flight it returns 409.\n- Within 10 minutes of a completed boost it returns the already-created ad instead of creating another.\n\nTo intentionally duplicate an ad, send distinct Idempotency-Keys (or vary the body, e.g. the name).\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","adAccountId","name","goal"],"properties":{"creativeFeatures":{"$ref":"#/components/schemas/MetaCreativeFeatures"},"postId":{"type":"string","description":"The Zernio post id (24 hex characters) returned when the post was created through Zernio. Send this or platformPostId. A value that is not a Zernio id is boosted as the platform post id, the same as platformPostId; a Zernio id that matches no post is a 404 on postId."},"platformPostId":{"type":"string","description":"Platform post ID (alternative to postId).\n\n- Reddit: the post id, with or without the `t3_` prefix.\n- Meta: a Page post id (`<pageId>_<postId>` or the bare post id) or an Instagram media id.\n- Meta Ads business-login connection (platform metaads): the id is resolved live. An Instagram media id is boosted as that media, running as the Instagram account that owns it."},"accountId":{"type":"string","description":"Zernio account id. Normally the connected posting account (facebook, instagram, tiktok, linkedin, pinterest, twitter), a googleads account or a redditads account.\n\nTikTok: the TikTok Ads connection (platform tiktokads) is also accepted when the post brings its own authorization (sparkAuthCode or sparkPosts), so Spark ads need no organic TikTok account connected. Such a call cannot use a Zernio postId: send the TikTok item id (as platformPostId, or in postId)."},"adAccountId":{"type":"string","description":"Platform ad account ID"},"name":{"type":"string","maxLength":255},"campaignName":{"type":"string","maxLength":255,"description":"Exact name for the campaign this boost provisions. Omitted keeps the default `<name> - Campaign`. Every platform: on LinkedIn it names the campaign group. Ignored on the Meta attach shape (`adSetId`), which creates no campaign."},"adSetName":{"type":"string","maxLength":255,"description":"Exact name for the ad-group level this boost provisions. Omitted keeps the default `<name> - Ad Group`. Meta: ad set; TikTok, Pinterest, Google: ad group; X: line item; LinkedIn: the campaign under the campaign group. Ignored on the Meta attach shape."},"goal":{"type":"string","enum":["engagement","traffic","awareness","video_views","lead_generation","conversions","app_promotion"],"description":"Available goals vary by platform. Meta (Facebook/Instagram) and TikTok support all 7. LinkedIn supports all except app_promotion. X supports engagement, traffic, awareness, video_views, app_promotion. Pinterest and Google Ads support only engagement, traffic, awareness, video_views. Reddit supports traffic, awareness, video_views, lead_generation and conversions."},"adSetId":{"type":"string","description":"Meta, or TikTok with `smartPlus: true`. Attach the boosted post to this existing ad set instead of creating a campaign.\n\n- Meta: the ad set then owns budget, schedule and targeting; sending those too is a 400.\n- TikTok: the id is an existing Smart+ ad group. The post is added as one more Spark ad (up to 30 per ad group), under the identity its `sparkAuthCode` creates. Goal and budget are inherited from the Smart+ campaign; a regular ad group is rejected with a 400."},"existingCampaignId":{"type":"string","description":"TikTok only. Create the ad group and the Spark ad under this existing TikTok campaign instead of creating a new campaign. The campaign keeps its own status and objective (the objective must fit `goal`). Cannot be combined with adSetId or smartPlus. On Meta use POST /v1/ads/create with existingCampaignId."},"identityId":{"type":"string","description":"TikTok only. The identity the ad runs as (the profile shown on the ad), from GET /v1/ads/tiktok-identities. Default: the connected TikTok account's own identity. Must be authorized on the advertiser or the call fails naming the available ones."},"identityType":{"type":"string","enum":["TT_USER","CUSTOMIZED_USER","BC_AUTH_TT"],"description":"TikTok only. Type of identityId; resolved from the advertiser's identity list when omitted."},"budgetAmount":{"type":"number","description":"Budget in whole currency units, the same flat field as POST /v1/ads/create. Required unless adSetId is set. Minimum varies: TikTok=$20, Pinterest=$5, others=$1"},"budgetType":{"type":"string","enum":["daily","lifetime"],"description":"Goes together with budgetAmount. lifetime requires schedule.endDate."},"lifetimeBudgetCap":{"type":"number","exclusiveMinimum":0,"description":"X only (400 on another platform or on a lifetime budget). A lifetime total, in whole currency units, that caps a daily budget (budgetType daily). Must be at least budgetAmount.\n\nThe line item gets both daily_budget_amount_local_micro and total_budget_amount_local_micro and stops spending once the total is reached. Read back as budget.daily and budget.lifetime."},"budget":{"type":"object","deprecated":true,"description":"Alias of budgetAmount + budgetType, kept for existing callers","required":["amount","type"],"properties":{"amount":{"type":"number","description":"Minimum varies: TikTok=$20, Pinterest=$5, others=$1"},"type":{"type":"string","enum":["daily","lifetime"]}}},"instagramAccountId":{"type":"string","description":"Meta only. Instagram identity the ad runs AS (creative.instagram_user_id), overriding the account linked to the Page. Live-verified against a Page-post creative."},"destinationType":{"type":"string","enum":["INSTAGRAM_PROFILE","WEBSITE","ON_AD","MESSENGER","WHATSAPP","INSTAGRAM_DIRECT"],"description":"Meta only. Ad-set destination_type: where the click LANDS, as opposed to instagramAccountId which is who the ad runs as. Independent of plain link CTAs and their goal. A messaging callToAction selects its destination automatically; an explicit destinationType must then match. Lead ads use ON_AD."},"whatsappPhoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"Meta WhatsApp only. E.164 number already paired with the Page. Omit to use the default pairing. Requires WHATSAPP_MESSAGE callToAction. Stored as creative.whatsappPhoneNumber on the ad."},"workflowId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Meta messaging boosts only (callToAction MESSAGE_PAGE, WHATSAPP_MESSAGE or INSTAGRAM_MESSAGE). A workflow in the account's profile, started in the conversation a click on the ad opens. Stored on the ad. 400 without a messaging callToAction or on another platform, 404 when no such workflow exists in the profile."},"currency":{"type":"string","minLength":3,"maxLength":3,"example":"USD","description":"ISO 4217 currency code matching the ad account's currency. Meta only. Optional: Zernio resolves it from the ad account when omitted. The value selects the minor-unit exponent Zernio converts budget/bid amounts by before calling Meta (most currencies are cents; zero-decimal currencies like JPY/KRW are sent as-is)."},"startDate":{"type":"string","format":"date-time","description":"Ad-set start time (ISO 8601, e.g. \"2026-06-10T09:00:00Z\"), mapped to the ad set's `start_time`. When omitted the ad starts delivering immediately. On Meta, TikTok, X, Pinterest and Reddit a value without an offset (`YYYY-MM-DD`, `YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DDTHH:MM:SS`) is read in the ad account timezone. Same field as on POST /v1/ads/create."},"endDate":{"type":"string","format":"date-time","description":"Ad-set end time (ISO 8601). Required for lifetime budgets. Same field as on POST /v1/ads/create.\n\nMaps to the ad set's `end_time` (on X, the line item's `end_time`; X campaigns carry no flight dates). On Pinterest it also goes on the campaign when the ad account needs Campaign Budget Optimization, daily budget included.\n\nOn Meta, TikTok, X, Pinterest and Reddit, a value without an offset (`YYYY-MM-DD`, `YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DDTHH:MM:SS`) is read in the ad account timezone, and a date-only end runs to 23:59:59 local.\n\nAnything that is not an ISO 8601 date or date-time is a 400 on `endDate`.\n"},"schedule":{"type":"object","deprecated":true,"description":"Alias of the top-level `startDate` / `endDate`, kept for existing callers. Sending both forms with differing values is a 400.","properties":{"startDate":{"type":"string","format":"date-time","deprecated":true,"description":"Alias of startDate, kept for existing callers"},"endDate":{"type":"string","format":"date-time","deprecated":true,"description":"Alias of endDate, kept for existing callers"}}},"targeting":{"type":"object","description":"Same geo/demographic fields as the `TargetingSpec` used by /v1/ads/create. Geo keys (`regions`/`cities`/`zips`/`metros`) resolve via GET /v1/ads/targeting/search?dimension=geo.\n\n- Meta only: city radius and lat/lng `customLocations`. They preserve the boosted post's social proof (the ad references the existing post).\n- Reddit: the whole `TargetingSpec` applies, including `communities`, `excludedCommunities`, `conversationKeywords`, `excludedConversationKeywords`, `interests`, `audienceInclude` / `audienceExclude` and `excludedLocations`. Without any geo the ad targets the US.\n","properties":{"ageMin":{"type":"integer","minimum":13,"maximum":65},"ageMax":{"type":"integer","minimum":13,"maximum":65},"gender":{"type":"string","enum":["all","male","female"],"description":"Applied on Meta, TikTok, Pinterest and Reddit. Ignored on Google, LinkedIn and X."},"languages":{"type":"array","items":{"type":"string"},"description":"Language codes, the same format as `languages` on POST /v1/ads/create.\n\n- Meta: ISO 639-1 codes. A bare code targets all regional variants (\"en\" = all English); use a region-qualified code for a specific one (\"en_GB\", \"pt_BR\"). Meta numeric locale ids (e.g. \"24\" for English UK) are also accepted. Unknown values are rejected.\n- Reddit: ISO 639-1 codes (e.g. `en`)."},"countries":{"type":"array","items":{"type":"string"},"description":"ISO country codes. Required for TikTok boosts (TikTok's ad group requires location_ids); optional on other platforms."},"regions":{"type":"array","description":"Region/state targeting. `key` 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 set together, Meta only).","items":{"type":"object","required":["key"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"radius":{"type":"number","description":"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)."},"distanceUnit":{"type":"string","enum":["mile","kilometer"]}}}},"zips":{"type":"array","description":"Postal/ZIP targeting. `key` is the platform's postal location ID (e.g. Meta `US:94304`).","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). No geo `key` lookup needed.","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"},"distanceUnit":{"type":"string","enum":["mile","kilometer"]},"name":{"type":"string"},"address":{"type":"string","description":"Optional label, sent to Meta as `address_string`."}}}},"interests":{"type":"array","description":"Interest objects from /v1/ads/interests. Each must include id and name.","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"advantage_audience":{"type":"integer","enum":[0,1],"description":"Meta only. 0 = disabled (default), 1 = enabled."}}},"locationTargetingType":{"allOf":[{"$ref":"#/components/schemas/GoogleLocationTargetingType"}],"description":"Google only (400 elsewhere). Written on the campaign the boost creates."},"rawTargeting":{"type":"object","additionalProperties":true,"description":"Meta only. A Meta-native targeting spec (e.g. `{ \"geo_locations\": { \"cities\": [{ \"key\": \"...\", \"radius\": 15, \"distance_unit\": \"kilometer\" }] } }`). Sent alone, it is forwarded unchanged. Use it for advanced fields the structured object does not expose (flexible_spec, excluded audiences, business places, user_os, wireless_carrier).\n\n**With `targeting`:** rawTargeting is the BASE layer and the built camelCase spec is merged on top, key by key (camelCase wins on collision).\n\n- The merge goes one level deep inside `geo_locations` and `excluded_geo_locations` (built sub-keys win; raw-only sub-keys such as `location_types` survive).\n- Array values (`flexible_spec`, ...) are replaced as a whole key, never element-merged.\n\n**`targeting_automation`.** When `rawTargeting` is present, Zernio no longer emits its usual `advantage_audience: 0` default, so it cannot clobber a `targeting_automation` in the raw spec. Meta requires `targeting_automation` on ad set creation: include it in the raw spec, or send `targeting.advantage_audience` (0 or 1), merged over raw as `targeting_automation`.\n"},"bidStrategy":{"allOf":[{"$ref":"#/components/schemas/BidStrategy"}],"deprecated":true,"description":"Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400.\n\nMeta bid strategy applied to the ad set. On TikTok, mapped to\n`bid_type` / `bid_price` / `deep_bid_type` automatically. On Reddit,\napplied to the new ad group (see the Reddit section above; 422 for\nLOWEST_COST_WITH_MIN_ROAS).\n"},"bidAmount":{"type":"number","deprecated":true,"description":"Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400.\n\nBid cap in WHOLE currency units (USD: 5 = $5.00; JPY: 100 = ¥100). Required when\n`bidStrategy` is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`. Backward-compat: providing\n`bidAmount` without `bidStrategy` is treated as `LOWEST_COST_WITH_BID_CAP`.\n"},"roasAverageFloor":{"type":"number","deprecated":true,"description":"Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400.\n\nMinimum ROAS as a decimal multiplier (e.g. 2.0 = 2.0x ROAS). Required when\n`bidStrategy` is `LOWEST_COST_WITH_MIN_ROAS`. Sent to Meta as\n`bid_constraints.roas_average_floor` × 10000 (Meta uses fixed-point integers).\n"},"platformSpecificData":{"description":"Platform-specific options. The platform is derived from `accountId`;\nsending options for a different platform returns a 400. LinkedIn\n(campaign bidding and delivery controls) and Meta (the bid trio)\nhave options today.\n\n**Meta**: `bidStrategy`, `bidAmount` and `roasAverageFloor` may be\nsent here instead of at the root, which is the preferred home going forward.\nSending the bid fields in BOTH places returns a 400\n(`mutually_exclusive_fields`).\n","oneOf":[{"$ref":"#/components/schemas/LinkedInAdsPlatformData"},{"$ref":"#/components/schemas/MetaAdsPlatformData"}]},"tracking":{"type":"object","description":"Meta only, except `pixelId`, which also picks the Reddit pixel of the new ad group (`promotedObject.pixelId` wins when both are sent). Tracking specs (pixel, URL tags).","properties":{"pixelId":{"type":"string"},"urlTags":{"type":"array","description":"URL parameters appended to the ad link, rendered as `key=value` pairs joined with `&`. Meta dynamic macros ({{ad.id}}, {{campaign.id}}, {{placement}}, ...) are sent through unescaped so Meta expands them; every other character is percent-encoded.","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}}}},"specialAdCategories":{"type":"array","description":"Special ad category of the campaign the boost creates. Required for housing, employment, credit, or political ads.\n\n- Meta: every value.\n- TikTok: HOUSING, EMPLOYMENT and CREDIT, sent as the campaign's `special_industries` (TikTok requires one for these ads aimed at the US or Canada). Other values return 400.\n- TikTok targeting: a 400 names the field for ZIP codes (`targeting.locations.zips`), gender, ages under 18 (`targeting.ageMin`), interest keywords (`keyword:` ids in `targeting.interests`) and hashtag behaviors.\n- TikTok also refuses Smart Targeting (`smartTargeting`) and lookalike audiences (`targeting.audienceInclude` / `targeting.audienceExclude`). Without an age, the ad group targets 18+.\n- TikTok sets the category when the campaign is created, so it is a 400 with `smartPlus` or `existingCampaignId`.\n","items":{"type":"string","enum":["HOUSING","EMPLOYMENT","CREDIT","FINANCIAL_PRODUCTS_SERVICES","ISSUES_ELECTIONS_POLITICS","ONLINE_GAMBLING_AND_GAMING"]}},"specialAdCategoryCountry":{"type":"array","description":"Meta (metaads) only. 2-letter ISO country codes the special ad category applies to. Requires specialAdCategories to be set (400 otherwise).","items":{"type":"string"}},"regionalRegulatedCategories":{"type":"array","description":"Meta only. Regional regulation categories required when the ad set targets certain countries (e.g. AUSTRALIA_FINSERV, AUSTRALIA_UNIVERSAL, BRAZIL_REGULATION, INDIA_FINSERV, MALAYSIA_UNIVERSAL, SINGAPORE_UNIVERSAL, TAIWAN_FINSERV, TAIWAN_UNIVERSAL, THAILAND_UNIVERSAL). Forwarded to the ad set.","items":{"type":"string"}},"regionalRegulationIdentities":{"type":"object","additionalProperties":{"type":["string","integer"]},"description":"Meta only. Verified identity IDs of the beneficiary and payer for each declared regionalRegulatedCategories value. Ignored when adSetId adds the ad to an existing ad set.\n\nMeta may require them on ad sets created through the API even when Ads Manager advertising settings have a default beneficiary and payer (seen on AUSTRALIA_FINSERV), so sending them explicitly is the reliable path.\n\nThe value is the Verified identity ID (Meta Business Settings > Verified identities), not a Page or Business ID. Beneficiary and payer may be the same ID. The IDs reach Meta unchanged.\n\nSend each ID as a string of digits: Verified identity IDs can have 17 digits, more than a JSON number holds exactly, and a number that arrives rounded is rejected. Numbers up to 9007199254740991 are still accepted.\n\nKeys by category:\n\n- AUSTRALIA_FINSERV: australia_finserv_beneficiary / australia_finserv_payer\n- TAIWAN_FINSERV: taiwan_finserv_beneficiary / taiwan_finserv_payer\n- INDIA_FINSERV: india_finserv_beneficiary / india_finserv_payer\n- TAIWAN_UNIVERSAL: taiwan_universal_beneficiary / taiwan_universal_payer\n- SINGAPORE_UNIVERSAL: singapore_universal_beneficiary / singapore_universal_payer\n- AUSTRALIA_UNIVERSAL, BRAZIL_REGULATION, MALAYSIA_UNIVERSAL and THAILAND_UNIVERSAL: universal_beneficiary / universal_payer\n\nWhen Meta rejects the ad set for a missing verified advertiser, the error carries param regionalRegulationIdentities, details.expectedIdentityKeys (the keys the declared categories expect), details.suggestedCategories (the markets Meta ties to that subcode) and Meta's metaCode, metaSubcode and fbtraceId.\n"},"linkUrl":{"type":"string","format":"uri","description":"Website URL for non-messaging CTA buttons. Send it with `callToAction`. Omit for messaging boosts.\n\n**Meta**: adds a top-level `call_to_action` to the post-reference creative.\nThis is what gives a `traffic` boost a clickable destination without\nreplacing the creative and losing the post's social proof. Ignored when\n`leadGenFormId` is set, which supplies its own destination. Live-verified\nagainst a Page-post creative.\n\n**TikTok**: maps to `landing_page_url` on the Spark Ad creative\n(`AdcreateCreatives.landing_page_url`); Spark Ads have no clickable\ndestination without it.\n\n**Reddit**: the ad's `click_url`, where a click on the promoted post lands.\n\nIgnored on LinkedIn / Pinterest / X / Google, which infer the destination\nfrom the boosted post.\n"},"callToAction":{"type":"string","description":"CTA button label. Non-messaging CTAs require `linkUrl`.\nWHATSAPP_MESSAGE, MESSAGE_PAGE, and INSTAGRAM_MESSAGE do not\nrequire a URL and reject linkUrl.\n\n**Meta**: the CTA enum of POST /v1/ads/create plus\n`VIEW_INSTAGRAM_PROFILE`, `WHATSAPP_MESSAGE`, `MESSAGE_PAGE`,\nand `INSTAGRAM_MESSAGE`. VIEW_INSTAGRAM_PROFILE requires linkUrl;\nthe messaging CTAs select their destination automatically.\n\n**TikTok**: pass-through to `call_to_action` on the Spark Ad creative; the\nplatform validates the value. See TikTok's \"Enumeration - Call-to-Action\".\n"},"sparkAuthCode":{"type":"string","description":"TikTok-only. Spark Code (the creator's `auth_code`) authorizing cross-creator Spark Ads: the advertiser can boost a video owned by a DIFFERENT TikTok account. Maps to `auth_code` on the creative entry of /v2/ad/create/.\n\nWithout it, boosts are limited to videos owned by the same account running the ads (same-BC creators only). The creator generates the code in their TikTok app's Promote settings and shares it with the advertiser.\n"},"smartPlus":{"type":"boolean","description":"TikTok only. Run the Spark post in a Smart+ campaign instead of a regular one: goal `conversions` = Smart+ Web Conversions, `lead_generation` = Smart+ Lead Generation. Rejected with a 400 on other platforms.\n\n**Requires:**\n\n- `sparkAuthCode`: the Smart+ ad runs the post under the identity created by redeeming its Spark code. A Business Center-owned post is not accepted.\n- `promotedObject.pixelId` + `customEventType`.\n\n`app_promotion` is not available on a Spark post.\n\nA Smart+ Spark ad uses a dynamic CTA portfolio, sent as ad_configuration.call_to_action_id (TikTok accepts no named call to action there). Zernio creates one per ad account and reuses it; `callToAction` is rejected with a 400 on this path."},"sparkPosts":{"type":"array","minItems":1,"maxItems":50,"description":"TikTok Smart+ only (requires `smartPlus: true`; a 400 on other platforms). Several Spark posts as creatives of ONE Smart+ ad, each with its own post code. Replaces `platformPostId` + `sparkAuthCode`.\n\nTikTok allows 1-50 per ad, and posts from different creators can mix.\n\n- Without `adSetId`: creates campaign + ad group + one ad carrying all of them.\n- With `adSetId`: creates one new ad with all of them in that ad group.\n","items":{"type":"object","required":["platformPostId","sparkAuthCode"],"properties":{"platformPostId":{"type":"string","description":"TikTok post (item) id."},"sparkAuthCode":{"type":"string","description":"That post's Spark code."}}}},"promoCodes":{"type":"array","minItems":1,"maxItems":10,"description":"TikTok Smart+ Web Conversions only (requires `smartPlus: true`, goal `conversions`). Promo codes or offers TikTok highlights on the ad (Ads Manager's \"Add promo code or offer\").\n\n- A promo code needs shoppers to enter it at checkout.\n- An entry without `promoCode` is an offer applied automatically.\n\nRejected with a 400 on other platforms and on Lead Generation campaigns.\n","items":{"type":"object","required":["discountType","discountValue"],"properties":{"discountType":{"type":"string","enum":["PERCENTAGE","CASH"]},"discountValue":{"type":"number","description":"PERCENTAGE: integer 1-100. CASH: amount greater than 0 in discountCurrency."},"discountCurrency":{"type":"string","description":"ISO 4217; required for CASH."},"promoCode":{"type":"string","maxLength":30,"description":"Code entered at checkout; omit for an automatic offer."},"minimumPurchaseType":{"type":"string","enum":["QUANTITY","SUBTOTAL"]},"minimumPurchaseValue":{"type":"number","description":"Required with minimumPurchaseType; QUANTITY is an integer >= 0, SUBTOTAL an amount > 0."},"minimumPurchaseCurrency":{"type":"string","description":"ISO 4217; required for SUBTOTAL."}}}},"promotedObject":{"type":"object","description":"Meta, TikTok and Reddit. What the conversion ad set optimizes toward, so a boost of an existing organic post can run for a conversion instead of only engagement or traffic. Required when `goal` is `conversions` (Meta also `lead_conversion`); ignored on goals that do not optimize for a conversion.\n\n- Meta: `pixelId` + `customEventType` (a commerce event such as PURCHASE under `conversions`, a leads-class event such as LEAD under `lead_conversion`), or `customConversionId` for a Custom Conversion, or `customEventType: OTHER` + `customEventStr` for a pixel custom event.\n- Meta: becomes the ad set `promoted_object`; without it Meta rejects the ad set (\"Please select a promoted object\", subcode 1815430). With `adSetId` the existing ad set already carries it.\n- TikTok: BOTH `pixelId` and `customEventType` are required. TikTok refuses a conversion ad group with no pixel (\"Please select a pixel\") or with a pixel but no event (\"Select a pixel event.\").\n- TikTok: combine freely with `platformPostId` + `sparkAuthCode`; the pixel lives on the ad group and the Spark item on the creative.\n- Reddit: every ad group carries a pixel, whatever the goal. `pixelId` picks it (default: the ad account's first pixel; 422 when the account has none).\n- Reddit: `conversions` requires `customEventType` (PURCHASE, LEAD, COMPLETE_REGISTRATION, SIGN_UP, ADD_TO_CART, PAGE_VISIT, VIEW_CONTENT or CONTENT_VIEW), and the pixel must already have received that event (422 otherwise). `lead_generation` needs the pixel to have received Lead.\n","properties":{"pixelId":{"type":"string","description":"Meta Pixel id, TikTok Pixel (numeric id or the alphanumeric pixel code from Events Manager, resolved for you), or Reddit pixel id."},"customEventType":{"type":"string","description":"Meta: standard pixel event (PURCHASE, LEAD, ...) or OTHER with customEventStr. TikTok: optimization_event code (e.g. ON_WEB_ORDER, SHOPPING, FORM) or the exact event name shown in Events Manager, resolved to its code; the event must already exist on that pixel."},"customEventStr":{"type":"string","description":"Meta only. Pixel custom event name as it appears in Events Manager; requires customEventType OTHER."},"customConversionId":{"type":"string","description":"Meta only. Custom Conversion to optimize against, instead of pixelId + customEventType."}}},"dsaBeneficiary":{"type":"string","maxLength":100,"description":"Legal entity that benefits from the ad. Required when targeting EU users\n(EU DSA, Article 26). Optional if the ad account has a default beneficiary:\nset it once via `PATCH /v1/ads/accounts` or in Meta Ads Manager, and Meta\nfills it in whenever the field is omitted.\n"},"dsaPayor":{"type":"string","maxLength":100,"description":"Legal entity that pays for the ad. Can differ from `dsaBeneficiary`\n(for example, an agency paying for a client's ads). Same rules as\n`dsaBeneficiary`: required for EU targeting unless the ad account has\na default payor.\n"},"leadGenFormId":{"type":"string","description":"Lead Gen form ID to attach to the boosted ad's creative. REQUIRED when `goal` is `lead_generation`; ignored for other goals.\n\n- Meta: the leadgen_forms ID (create one via POST /v1/ads/lead-forms).\n- LinkedIn: the adForm ID (create one via POST /v1/ads/lead-forms with a LinkedIn account). The creative's `leadgenCallToAction.destination` is set to `urn:li:adForm:{id}`.\n- Reddit: rejected with 400 on every goal (Reddit retired its native lead forms)."},"status":{"type":"string","enum":["ACTIVE","PAUSED"],"description":"Publish state of the created entities, on every platform. Omitted or ACTIVE publishes live (default).\n\nPAUSED pauses only the top-most object this boost creates and switches everything below it on:\n\n- New campaign: held paused with its ad set and ad on. One PUT /v1/ads/campaigns/{campaignId}/status with `active` brings it live.\n- Into an existing campaign (TikTok `existingCampaignId`): the new ad set is held paused.\n- Attached to an existing ad set (`adSetId`): the new ad itself is paused.\n- LinkedIn: every object the boost creates is held. A new campaign group is PAUSED, and its campaign and creative stay DRAFT. Resume each held object top-down to go live.\n- X: has no per-ad switch, so its lowest level is the line item.\n\n`campaignStatus`, `adSetStatus` and `adStatus` set one level each and always win for that level. `status: PAUSED` adds a hold of its own only when none of them is PAUSED. To create every object paused, send all three as PAUSED.\n"},"campaignStatus":{"type":"string","enum":["ACTIVE","PAUSED"],"description":"Every platform, same semantics as POST /v1/ads/create. Sets the switch of the new campaign alone (LinkedIn: the campaign group) and overrides `status` for it. When omitted, it follows `status`.\n\n`ACTIVE` with `status: PAUSED` switches the campaign on and holds the new ad set paused (its ad on).\n\nRejected with a 400 alongside `adSetId` or `existingCampaignId`, where no campaign is created (change an existing one with PUT /v1/ads/campaigns/{campaignId}/status).\n"},"adSetStatus":{"type":"string","enum":["ACTIVE","PAUSED"],"description":"Every platform, same semantics as POST /v1/ads/create. Sets the switch of the new ad set alone and overrides `status` for it. Omitted, it follows `status`.\n\nThe ad set is the ad group on Google, TikTok and Pinterest; the campaign on LinkedIn (it stays DRAFT when held); the line item on X.\n\n**Precedence.** A level status (`campaignStatus`, `adSetStatus`, `adStatus`) always wins for its level. `status: PAUSED` then holds the top-most new object without a level status, only when no level status is PAUSED; every other new object is switched on.\n\nSo `campaignStatus: ACTIVE` + `adSetStatus: PAUSED` + `adStatus: PAUSED` keeps the campaign on with the new ad set and ad off, and all three PAUSED create the whole tree paused.\n\nRejected with a 400 alongside `adSetId` (that ad set already exists; change it with PUT /v1/ads/ad-sets/{adSetId}/status).\n"},"adStatus":{"$ref":"#/components/schemas/AdActivationStatus","description":"Sets the switch of the new ad alone, also when attaching to an existing ad set with `adSetId` (Meta, TikTok Smart+), and overrides `status` for it. Same precedence as `adSetStatus`. Omitted, it follows `status`.\n\n- LinkedIn: a creative held off is created DRAFT, because LinkedIn refuses PAUSED on a creative until its review is APPROVED. A DRAFT creative is not submitted for review and cannot serve; it reads `paused`. Resuming the ad (PUT /v1/ads/{adId}/status `active`) switches it ACTIVE, which starts the review.\n- X: returns a 400. A promoted post has no switch of its own, so hold the line item with `adSetStatus`.\n"},"budgetLevel":{"type":"string","enum":["adset","campaign"],"description":"Meta only, same semantics as POST /v1/ads/create: campaign = Advantage campaign budget (CBO), the budget and bid strategy sit on the campaign and the ad set inherits them. Default adset. Not allowed with adSetId."},"attributionSpec":{"type":"array","minItems":1,"maxItems":3,"description":"Meta only. Ad-set attribution windows, same shape as POST /v1/ads/create. Applied on OUTCOME_SALES, OUTCOME_LEADS and OUTCOME_APP_PROMOTION campaigns (conversions, lead_conversion, lead_generation, app_promotion); other objectives keep Meta's default. Not allowed with adSetId.","items":{"type":"object","required":["eventType","windowDays"],"properties":{"eventType":{"type":"string","enum":["CLICK_THROUGH","VIEW_THROUGH","ENGAGED_VIDEO_VIEW"]},"windowDays":{"type":"integer","enum":[1,7,28]}}}},"bodies":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string"},"description":"Meta only. Extra primary-text options Meta rotates on the boosted post (asset_feed_spec.bodies with DEGREES_OF_FREEDOM). The post keeps its own text as one of the options. Works for Facebook posts and Instagram media.\n\nUnder a conversions or traffic goal, Meta also wants a website URL on the options, taken from `linkUrl` (send it with a `callToAction`). Engagement boosts need none.\n"},"retryOnServerError":{"type":"boolean","description":"Meta only (a 400 elsewhere). When Meta answers a create with a 5xx and reading the parent back by name finds no such object, Zernio sends the create again (at most 3 POSTs per object, never for an object created ACTIVE) and reports it in `recoveredWrites`.\n\n`false` never sends it again: the request fails with 502 and `details.unconfirmedWrite`, so you can check the parent yourself. One object found by name is still reused.\n"},"rehostOnInstagramVideoRejection":{"type":"boolean","description":"Meta only (a 400 elsewhere). Controls the fallback when Meta refuses an existing Instagram video as the ad (subcode 1815279).\n\n- First, Zernio copies the video into the ad account and retries on the original post.\n- Then it falls back to a new Facebook video in a new Page post, which does not show the original post's likes and comments.\n\nThe response reports which in `instagramVideoFallback`. Messaging boosts never use the unlinked copy. `false` skips every fallback and returns Meta's error.\n"},"smartTargeting":{"type":"object","description":"TikTok only (a 400 elsewhere). TikTok Smart Targeting on the ad group: `audience` is TikTok's `smart_audience_enabled`, `interestsBehaviors` its `smart_interest_behavior_enabled`. When on, TikTok may deliver beyond the selected audiences or interests.\n\nAvailable on Video views, Traffic, Lead generation, App install, Web conversion and Community interaction. Not available with smartPlus or when attaching to an existing ad set (adSetId).\n\nOnly the flags you send are written. An unwritten flag reads back null in `nativeSettings`, so send `false` explicitly to be able to verify it is off.\n","properties":{"audience":{"type":"boolean","description":"TikTok smart_audience_enabled."},"interestsBehaviors":{"type":"boolean","description":"TikTok smart_interest_behavior_enabled."}}},"optimizationGoal":{"type":"string","description":"Ad-set optimization goal override. Meta, or TikTok with `goal: video_views`.\n\n**TikTok**: ENGAGED_VIEW (6-second Focused View, the default) or ENGAGED_VIEW_FIFTEEN (15-second views), both billed per view (CPV). Any other value is a 400.\n\n**Meta**: explicit ad-set `optimization_goal` override. When omitted, defaults to the value derived from `goal`.\n\n- Messaging boosts always use CONVERSATIONS and reject other values.\n- Otherwise the value must fit the objective Meta derives from `goal` for boosts, not the one `POST /v1/ads/create` uses for the same name. Boost maps `goal: \"engagement\"` to `OUTCOME_AWARENESS`, which accepts `REACH`, `IMPRESSIONS`, `AD_RECALL_LIFT`, or THRUPLAY-class values.\n- `POST_ENGAGEMENT` with `goal: engagement` opts into `OUTCOME_ENGAGEMENT` with `destination_type` `ON_POST`, exactly like `metaObjective: OUTCOME_ENGAGEMENT` (sending both is the same request).\n- `POST_ENGAGEMENT` returns 400 with any other `goal`, with `leadGenFormId`, or with a `CALL_NOW` or messaging `callToAction`.\n- Under `OUTCOME_ENGAGEMENT` the ad runs on the post, so `destinationType` is a 400 (messaging CTAs excepted) and `optimizationGoal` must be `POST_ENGAGEMENT` or `REACH`. Meta no longer offers `IMPRESSIONS` there; a plain engagement boost on `OUTCOME_AWARENESS` still accepts it.\n- With `adSetId` the ad joins an existing ad set and `optimizationGoal` is not read.\n\nThe created ad reports the objective and optimization goal Meta runs it with in `platformObjective` and `optimizationGoal` (with `adSetId`, those of the existing ad set).\n"},"metaObjective":{"type":"string","enum":["OUTCOME_ENGAGEMENT"],"description":"Meta only, with `goal: engagement` and without `adSetId` (400 otherwise).\n\n`OUTCOME_ENGAGEMENT` creates the campaign with objective `OUTCOME_ENGAGEMENT` and the ad set with `optimization_goal` `POST_ENGAGEMENT` (unless `optimizationGoal` is set) and `destination_type` `ON_POST`: the shape Ads Manager uses to boost an existing post.\n\n- `optimizationGoal: POST_ENGAGEMENT` selects the same objective, so the two may be sent together.\n- `destinationType` returns 400 (messaging CTAs excepted); `optimizationGoal` must be `POST_ENGAGEMENT` or `REACH` (400 otherwise).\n- When both are omitted, an engagement boost keeps `OUTCOME_AWARENESS` with `REACH`.\n- Returns 400 with `leadGenFormId` or a `callToAction` whose objective is not `OUTCOME_ENGAGEMENT` (`CALL_NOW`). Messaging CTAs keep their own `CONVERSATIONS` ad set.\n\nVerified against Meta on Facebook posts; Instagram posts are accepted but not yet verified.\n"},"validateOnly":{"type":"boolean","description":"Meta only (facebook, instagram and Meta ads connections). Dry-runs the boost with Meta's execution_options validate_only: the campaign, ad set, creative (the post reference) and ad are checked as sent, everything PAUSED, and nothing is created or stored on Meta or in Zernio.\n\nReturns 200 with the same body as a validateOnly POST /v1/ads/create (`validateOnly`, `results` per node, `message`).\n\n- Idempotency-Key storage and the duplicate-boost guard are bypassed.\n- Counts toward the 30 Meta writes per ad account per 5 minutes.\n- Runs the account status and payment checks of GET /v1/ads/accounts/health first: an ad account that is not ready answers its blocker `code` (`ad_account_unusable`, `ad_account_payment_required`) with `details.hint` and `details.fix`, and Meta is not called.\n- With `adSetId`, only the ad is dry-run.\n- An Instagram video Meta refuses as a direct reference (subcode 1815279) comes back as `unverified` nodes, because the copy a real boost makes cannot be dry-run.\n\n`true` on any other platform returns 400 naming `validateOnly` and creates nothing; `false` is ignored. `dryRun` is not a field: sending it returns 400 instead of creating the ad.\n"}}},"example":{"accountId":"69ca62446cb7b8cf4cb13603","adAccountId":"act_757082720485182","platformPostId":"811889972008357_123456789","name":"WhatsApp post boost","goal":"engagement","callToAction":"WHATSAPP_MESSAGE","whatsappPhoneNumber":"+12025550123","budget":{"amount":2.61,"type":"daily"},"status":"PAUSED"}}}},"responses":{"200":{"description":"validateOnly dry-run passed (Meta), nothing was created","content":{"application/json":{"schema":{"type":"object","properties":{"validateOnly":{"type":"boolean","description":"Always true in a validate-only response."},"results":{"type":"array","items":{"type":"object","properties":{"node":{"type":"string","enum":["campaign","adSet","creative","ad"]},"status":{"type":"string","enum":["validated","skipped","unverified"]},"reason":{"type":"string","description":"Why the node was skipped (it already exists with adSetId), why Meta could not dry-run it (on unverified), or what the dry run could not check (on validated)."}}}},"message":{"type":"string"}}}}}},"201":{"description":"Ad created","content":{"application/json":{"schema":{"type":"object","properties":{"ad":{"$ref":"#/components/schemas/Ad"},"message":{"type":"string"},"instagramVideoFallback":{"$ref":"#/components/schemas/InstagramVideoFallback"},"recoveredWrites":{"$ref":"#/components/schemas/MetaRecoveredWrites"},"warnings":{"type":"array","items":{"type":"string"},"description":"Human-readable notes about the boost.\n\n- **With instagramVideoFallback:** one line saying how the Instagram video was boosted.\n- **`activation_failed:` (Meta):** Meta refused the final switch to ACTIVE of the campaign, ad set or ad this boost created. Nothing was deleted and `message` says not everything is ACTIVE.\n- **`activation_failed:` content:** names what was kept PAUSED and what was switched ACTIVE, and quotes Meta's error and the status calls that switch the PAUSED ones on later.\n- **`replayed_paused:`:** a retry without Idempotency-Key inside the 10-minute dedup window found the stored ad PAUSED although it asks for ACTIVE. Carries the same status calls.\n"}}}}}},"400":{"x-summary":"Required fields are missing, values are invalid, or the platform rejected validation: fix the request and resend.","description":"Missing required fields or invalid values, `validateOnly: true` outside Meta, `dryRun` sent, or a Meta validateOnly validation failure (verbatim)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is blocked: enable the Ads add-on, add a card, select the ad account, or grant the user Advertise permission.","description":"Ads access required. Legacy plans need the Ads add-on; it is included by default on usage-based plans. Also returned with these codes:\n\n- `ads_allowance_exceeded`: the team has no payment method on file and has reached the 500 free live ads. Add a card to resume.\n- `ad_account_not_selected`: the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n- `ad_account_not_selected` fix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection), or use a connection that has it selected.\n- `insufficient_permissions`: the Facebook user behind the token lacks the Advertise permission on the Meta ad account, or the token lacks `ads_management` (Meta subcode 2490585, 2490591 or 4841020; see `ErrorResponse.details`).\n"},"404":{"x-summary":"The account or post was not found: check the ID, or send `platformPostId` for posts published outside Zernio.","description":"Code `account_not_found` (`accountId`), or `post_not_found` (`postId`) when a Zernio post id matches no post this key can reach. A post published outside Zernio goes in platformPostId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"x-summary":"The account needs reconnection or an identical boost is already running: reconnect it or wait for the running request to finish.","description":"The account may also be inactive or need reconnection (code ads_connection_required). Reconnect it and read GET /v1/accounts for its current ID before retrying.\nAn identical boost request is already in progress (with or without\nan Idempotency-Key). Wait for it to finish instead of retrying.\n"},"422":{"x-summary":"The request cannot proceed: connect the ads account, use a new idempotency key, or fix the ad account status.","description":"Returned with one of these codes:\n\n- `ads_connection_required`: platform ads connection required (TikTok Ads, X Ads), missing linked account, or (for TikTok) the connected TikTok user is not authorized as an Identity on the target advertiser. The message includes the actionable \"TikTok Ads Manager → Assets → Identity\" remediation step.\n- `idempotency_key_reused`: an Idempotency-Key was reused with a different request body.\n- `ad_account_unusable`: Meta refuses writes on the ad account because its status is ineligible to manage ads (see `ErrorResponse.details`).\n"},"429":{"$ref":"#/components/responses/MetaAdAccountWriteLimited"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/v1/ads/campaigns/{campaignId}/asset-groups":{"get":{"x-resource-group":"ads","operationId":"listGoogleAssetGroups","summary":"List Performance Max asset groups","tags":["Ad Campaigns"],"x-platforms":["google"],"description":"Lists a Performance Max campaign's asset groups with their linked text, image and YouTube assets.\n\ncampaignId is the platform campaign id returned by creation or the campaign list. The campaign must be visible to the caller.\n\n### Caching\n\nUses a 10-minute cache, with the last successful response served as stale when Google quota is exhausted.\n\n### What is left out\n\n- Removed groups and asset links are excluded.\n- Campaign-level brand assets on campaigns with brand guidelines enabled are not included.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Google Ads campaign id."}],"responses":{"200":{"description":"Asset groups and linked assets.","content":{"application/json":{"schema":{"type":"object","required":["assetGroups","cachedAt","stale"],"properties":{"assetGroups":{"type":"array","items":{"$ref":"#/components/schemas/GooglePmaxAssetGroup"}},"cachedAt":{"type":["string","null"],"format":"date-time"},"stale":{"type":"boolean"}}},"example":{"assetGroups":[{"id":"123456789","resourceName":"customers/9122445560/assetGroups/123456789","name":"Social publishing","status":"ENABLED","finalUrls":["https://zernio.com"],"assets":[{"resourceName":"customers/9122445560/assets/987654321","fieldType":"HEADLINE","status":"ENABLED","text":"Schedule posts"}]}],"cachedAt":"2026-09-10T09:00:00Z","stale":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Google quota or operation budget exhausted with no cached response."},"501":{"description":"Campaign is not on Google Ads."}}},"post":{"x-resource-group":"ads","operationId":"createGoogleAssetGroup","summary":"Create a Performance Max asset group","tags":["Ad Campaigns"],"x-platforms":["google"],"security":[{"bearerAuth":[]}],"description":"Adds an asset group with its assets and optional product targeting to a Performance Max campaign, or just validates it without creating anything.\n\nThe group, any new assets, their links and an optional listing-group tree are created in one atomic request, so Google checks the asset minimums (for non-retail campaigns) against the whole set. Created PAUSED unless status is ENABLED. validateOnly: true runs Google's validation without creating anything.\n\nA campaign that is not Performance Max returns 400 on campaignId (add an ad group with POST /v1/ads/ad-sets instead). A missing or removed campaign returns 404.\n","parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Google Ads campaign id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","finalUrls"],"properties":{"name":{"type":"string","minLength":1,"maxLength":128,"description":"Unique within the campaign."},"finalUrls":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","format":"uri"}},"finalMobileUrls":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","format":"uri"}},"path1":{"type":"string","maxLength":15},"path2":{"type":"string","maxLength":15,"description":"Requires path1."},"status":{"type":"string","enum":["ENABLED","PAUSED"],"default":"PAUSED"},"assets":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/GoogleAssetGroupAssetLink"}},"listingGroupFilter":{"$ref":"#/components/schemas/GoogleListingGroupTree"},"validateOnly":{"type":"boolean","default":false}}},"example":{"name":"Running shoes","finalUrls":["https://example.com/shoes"],"assets":[{"fieldType":"HEADLINE","text":"Shoes for every run"},{"fieldType":"LOGO","asset":"customers/9122445560/assets/352426364803"}]}}}},"responses":{"200":{"x-summary":"Google accepted the validation-only request and nothing was created.","description":"validateOnly request accepted by Google. Nothing was created.","content":{"application/json":{"schema":{"type":"object","properties":{"validateOnly":{"type":"boolean"},"message":{"type":"string"}}}}}},"201":{"description":"Asset group created.","content":{"application/json":{"schema":{"type":"object","required":["assetGroup"],"properties":{"assetGroup":{"type":"object","required":["id","resourceName","campaignId"],"properties":{"id":{"type":"string"},"resourceName":{"type":"string"},"campaignId":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Google Ads connection needs reconnecting."},"429":{"description":"Google quota or the Zernio Google operations burst limit is exhausted."},"501":{"description":"Campaign is not on Google Ads."}}}},"/v1/ads/campaigns/{campaignId}/asset-groups/{assetGroupId}":{"get":{"x-resource-group":"ads","operationId":"getGoogleAssetGroup","summary":"Get a Performance Max asset group","tags":["Ad Campaigns"],"x-platforms":["google"],"security":[{"bearerAuth":[]}],"description":"Shows one Performance Max asset group with its linked assets, ad strength, status and product targeting tree.\n\nOne asset group with its linked assets, ad strength, primary status and listing-group tree. Uses a 10-minute cache, served stale when Google quota is exhausted; any write below clears it.\n","parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Google Ads campaign id."},{"name":"assetGroupId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Google asset group id."}],"responses":{"200":{"description":"The asset group.","content":{"application/json":{"schema":{"type":"object","required":["assetGroup","cachedAt","stale"],"properties":{"assetGroup":{"$ref":"#/components/schemas/GooglePmaxAssetGroupDetail"},"cachedAt":{"type":["string","null"],"format":"date-time"},"stale":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Google Ads connection needs reconnecting."},"429":{"description":"Google quota or the Zernio Google operations burst limit is exhausted."},"501":{"description":"Campaign is not on Google Ads."}}},"patch":{"x-resource-group":"ads","operationId":"updateGoogleAssetGroup","summary":"Update a Performance Max asset group","tags":["Ad Campaigns"],"x-platforms":["google"],"security":[{"bearerAuth":[]}],"description":"Changes a Performance Max asset group's name, status, final URLs or display paths.\n\nChange the name, status (ENABLED or PAUSED), final URLs or display paths. Only the fields sent are written; null on path1 or path2 clears it. Change assets with the /assets endpoint and product targeting with /listing-group-filters. validateOnly: true validates without writing.\n","parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Google Ads campaign id."},{"name":"assetGroupId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Google asset group id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"status":{"type":"string","enum":["ENABLED","PAUSED"]},"finalUrls":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","format":"uri"}},"finalMobileUrls":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","format":"uri"}},"path1":{"type":["string","null"],"maxLength":15},"path2":{"type":["string","null"],"maxLength":15},"validateOnly":{"type":"boolean","default":false}}},"example":{"status":"PAUSED","finalUrls":["https://example.com/sale"]}}}},"responses":{"200":{"description":"Updated (or validated).","content":{"application/json":{"schema":{"type":"object","properties":{"assetGroupId":{"type":"string"},"updated":{"type":"array","items":{"type":"string"}},"validateOnly":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Google Ads connection needs reconnecting."},"429":{"description":"Google quota or the Zernio Google operations burst limit is exhausted."},"501":{"description":"Campaign is not on Google Ads."}}},"delete":{"x-resource-group":"ads","operationId":"removeGoogleAssetGroup","summary":"Remove a Performance Max asset group","tags":["Ad Campaigns"],"x-platforms":["google"],"security":[{"bearerAuth":[]}],"description":"Permanently removes an asset group from a Performance Max campaign (this cannot be undone).\n\nRemoves the asset group on Google (status REMOVED, not reversible). Pass validateOnly=true to validate without removing.\n","parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"}},{"name":"assetGroupId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"}},{"name":"validateOnly","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Removed (or validated).","content":{"application/json":{"schema":{"type":"object","properties":{"assetGroupId":{"type":"string"},"removed":{"type":"boolean"},"validateOnly":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Google Ads connection needs reconnecting."},"429":{"description":"Google quota or the Zernio Google operations burst limit is exhausted."},"501":{"description":"Campaign is not on Google Ads."}}}},"/v1/ads/campaigns/{campaignId}/asset-groups/{assetGroupId}/assets":{"post":{"x-resource-group":"ads","operationId":"editGoogleAssetGroupAssets","summary":"Link or unlink asset group assets","tags":["Ad Campaigns"],"x-platforms":["google"],"security":[{"bearerAuth":[]}],"description":"Links new or existing assets to a Performance Max asset group and unlinks others in one change, keeping unlinked assets in the account library.\n\nLink existing assets or new content to the asset group, and unlink assets, in one atomic request.\n\n- Links are applied before unlinks, so swapping the last asset of a role does not trip Google's per-role minimum.\n- Unlinking removes the link only; the asset stays in the account library.\n- validateOnly: true validates without writing.\n","parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Google Ads campaign id."},{"name":"assetGroupId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Google asset group id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"link":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/GoogleAssetGroupAssetLink"}},"unlink":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/GoogleAssetGroupAssetUnlink"}},"validateOnly":{"type":"boolean","default":false}}},"example":{"link":[{"fieldType":"HEADLINE","text":"Free shipping today"}],"unlink":[{"fieldType":"HEADLINE","asset":"customers/9122445560/assets/419573236135"}]}}}},"responses":{"200":{"description":"Links applied (or validated).","content":{"application/json":{"schema":{"type":"object","properties":{"assetGroupId":{"type":"string"},"linked":{"type":"integer"},"unlinked":{"type":"integer"},"validateOnly":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Google Ads connection needs reconnecting."},"429":{"description":"Google quota or the Zernio Google operations burst limit is exhausted."},"501":{"description":"Campaign is not on Google Ads."}}}},"/v1/ads/campaigns/{campaignId}/asset-groups/{assetGroupId}/listing-group-filters":{"put":{"x-resource-group":"ads","operationId":"replaceGoogleListingGroupFilters","summary":"Replace an asset group's listing-group tree","tags":["Ad Campaigns"],"x-platforms":["google"],"security":[{"bearerAuth":[]}],"description":"Replaces the product targeting tree of a Performance Max retail asset group; only works on campaigns linked to Merchant Center.\n\nThe current product (listing-group) tree is removed and the new one created in one atomic request. Read the current tree with GET on the asset group.\n\n- Requires a campaign linked to Merchant Center. Other campaigns return 400 LISTING_SOURCE_NOT_ALLOWED from Google.\n- validateOnly: true validates without writing.\n","parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Google Ads campaign id."},{"name":"assetGroupId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Google asset group id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tree"],"properties":{"tree":{"$ref":"#/components/schemas/GoogleListingGroupTree"},"validateOnly":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Tree replaced (or validated).","content":{"application/json":{"schema":{"type":"object","properties":{"assetGroupId":{"type":"string"},"removed":{"type":"integer","description":"Nodes removed from the previous tree."},"created":{"type":"integer","description":"Nodes in the new tree."},"validateOnly":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Google Ads connection needs reconnecting."},"429":{"description":"Google quota or the Zernio Google operations burst limit is exhausted."},"501":{"description":"Campaign is not on Google Ads."}}}},"/v1/ads/create":{"post":{"x-resource-group":"ads","operationId":"createStandaloneAd","tags":["Ad Campaigns"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","openai","reddit","microsoft"],"summary":"Create standalone ad","description":"Creates a paid ad with your own creative, building the campaign and ad set it needs or adding it to existing ones.\n\nWorks across Meta, Google Ads, Pinterest, TikTok, X, LinkedIn, OpenAI Ads (ChatGPT Ads), Reddit Ads and Microsoft Ads. Per-platform required fields, budget minimums, and video-ad rules are documented on each property below.\n\n### Request shapes\n\nThe body selects one of these mutually exclusive shapes:\n\n- Legacy single-creative shape (all platforms, the default).\n- Meta-only multi-creative shape via the creatives array: one ad set with N ads sharing budget and targeting.\n- Attach shape via adSetId: adds one new ad to an existing ad set, inheriting its budget, targeting, and schedule (Meta, Google Ads, TikTok, and LinkedIn).\n\nOn LinkedIn, adSetId in the attach shape is the existing Campaign id, and the budget, schedule, targeting and bidding fields must be omitted. `goal` may be omitted too (taken from the Campaign's objective), and the created ad's `targeting` echoes the Campaign's audience.\n\n### Google Performance Max\n\nSet `campaignType: \"pmax\"` and supply `assetGroup` with text, images by role, business name and finalUrl. This creates a daily budget, PAUSED campaign and asset group atomically.\n\n- `validateOnly: true` validates the complete request with Google without creating or persisting resources.\n- Read assets with `GET /v1/ads/campaigns/{campaignId}/asset-groups`.\n- The logo is required; video is optional via `assetGroup.youtubeVideoId`.\n- Brand guidelines are disabled at creation.\n- All supplied asset links are validated together against Google's minimum asset requirements.\n- PMax rejects ACTIVE creation, portfolio bidding, bid caps, legacy creative fields and attach shapes.\n- Geo and language targeting are supported; omitted geo targets all locations.\n- PMax does not require top-level goal, headline, body or linkUrl.\n\nSupported bidding:\n\n- Omitted or LOWEST_COST_WITHOUT_CAP: Maximize Conversions.\n- COST_CAP plus bidAmount: target CPA.\n- LOWEST_COST_WITH_MIN_ROAS plus roasAverageFloor: Maximize Conversion Value with target ROAS.\n\n### Google Demand Gen\n\nSet `campaignType: \"demand_gen\"` and supply `demandGen`. One atomic request creates a daily budget, PAUSED campaign, one ad group and one ad. The ad is:\n\n- a multi-asset image ad by default;\n- a video responsive ad when `demandGen.youtubeVideoIds` is sent;\n- a carousel ad (2 to 10 cards) when `demandGen.carouselCards` is sent.\n\nTargeting and validation:\n\n- Geo (countries, regions, cities, zips, metros) and languages go on the ad group, as Demand Gen requires.\n- `demandGen.channels` sets the ad group's channel controls.\n- `demandGen.audience` builds a Google Audience (user lists, interests, custom audiences, age ranges, genders) attached to the ad group, or `demandGen.audienceId` attaches an existing one.\n- `validateOnly: true` validates everything with Google without creating resources.\n\nSupported bidding:\n\n- Omitted or LOWEST_COST_WITHOUT_CAP: Maximize Conversions.\n- COST_CAP plus bidAmount: target CPA.\n- LOWEST_COST_WITH_MIN_ROAS plus roasAverageFloor: target ROAS.\n- LOWEST_COST_WITH_BID_CAP plus bidAmount: target CPC.\n\nThe created ad carries the native `platformCampaignId`, `platformAdSetId` (ad group) and `platformAdId`. After creation:\n\n- Activate with PUT /v1/ads/campaigns/{campaignId}/status.\n- Edit budget, bidding and name with the regular campaign endpoints.\n- Edit creative, channels, audience and ad group targeting with PUT /v1/ads/{adId} (`demandGen`, `targeting`).\n\nTo grow an existing Demand Gen campaign, send one of these (neither takes budget, bidding or schedule fields; both support `validateOnly`):\n\n- `existingCampaignId`: adds a PAUSED ad group, with its own geo, languages, channels and audience, plus its ad.\n- `adSetId`: adds a PAUSED ad to that ad group.\n\n### Meta creative options\n\nMeta accepts `creativeFeatures` on the single and attach shapes and as defaults for `creatives[]`; an item replaces the whole feature map.\n\n`promotion` is not supported on any shape, and any object is rejected with 400.\n\nReusing `existingCreativeId` uses the existing creative settings instead of new settings. Requested settings are persisted for lists, exports, and default ad-detail reads.\n\n### Meta required fields per shape\n\nA missing field is a 400 naming it in `param`.\n\n- Every shape that builds a new ad set (no `adSetId`, `existingCampaignId` or `buyingType: \"RESERVED\"`): `budgetAmount`. `budgetType` defaults to daily, and a lifetime budget without `endDate` ends 7 days after it starts (see `appliedDefaults`).\n- Single image or video (the default), also with `adSetId`: `headline` (max 255), `body`, `callToAction`, and exactly one of `imageUrl` / `video`. A catalog template creative takes none, and ignores and does not upload any sent.\n- Single image or video also needs `linkUrl`, unless the goal is `lead_generation` or `page_visits` or `leadGenFormId` is set.\n- `bodies[]` / `headlines[]` text variations: `body`, one list with 2+ items, `callToAction`, `imageUrl` or `video`, and `linkUrl` unless the goal is `lead_generation` or `leadGenFormId` is set. `headline` is not required.\n- `placementAssets`: `headline`, `body`, `callToAction`, and `linkUrl` with the same exemptions as the single shape; the media comes from `placementAssets`.\n- `carouselCards`: `body`, `callToAction`, and `linkUrl` unless the goal is `lead_generation` or `leadGenFormId` is set. `headline` is not required.\n- `creatives[]`: per entry `headline`, `body`, `callToAction`, `imageUrl` or `video`, and `linkUrl` unless the goal is `lead_generation`. Top-level `body` is not required.\n- `dynamicCreative`: `imageUrls` or `videoUrls`, `callToActionTypes`, and `linkUrls` unless the goal is `lead_generation`. Top-level `body` is not required.\n- `existingCreativeId`: no creative fields.\n- Goal `page_likes`: `body` only.\n- Goal `lead_generation` always needs `leadGenFormId`, except with `existingCreativeId`.\n\n### Meta activation\n\nMeta builds the campaign, ad set and ads PAUSED and switches the requested levels to ACTIVE as the last step.\n\nWhen Meta refuses that switch, or the connection drops, after Zernio's retries, the request still answers 201 and nothing is deleted:\n\n- The refused level and every level below it stay PAUSED.\n- Levels above it that already went ACTIVE stay ACTIVE.\n- The ad comes back with `status: paused` and its `configuredStatus` as read back from Meta.\n- A switch Meta applied although its answer was lost counts as ACTIVE, since Zernio reads the status back first.\n\n`message` says not everything is ACTIVE. `warnings` carries one entry starting with `activation_failed:` that quotes Meta's code, subcode and message, and names what was kept PAUSED and what was switched ACTIVE.\n\nThat warning also lists the calls that switch the PAUSED ones on later, in this order, with status `active`:\n\n1. PUT /v1/ads/campaigns/{campaignId}/status\n2. PUT /v1/ads/ad-sets/{adSetId}/status\n3. PUT /v1/ads/{adId}/status\n\nOn the `creatives[]` shape, only the ads Meta refused stay PAUSED when the campaign and ad set went through. A Reach and Frequency ad is created ACTIVE and is never listed as kept PAUSED. With an `Idempotency-Key`, a retry replays this 201.\n\n### LinkedIn\n\nLinkedIn creates a Single Image or Single Video Ad backed by a Direct Sponsored Content \"dark post\" authored by a Company Page (see `organizationId`).\n\n- Supported goals: engagement, traffic, awareness, and video_views.\n- Video ads use the `video` field; video_views requires a video.\n- Traffic ads require `linkUrl`.\n\n### Reddit Ads\n\nUse the `accountId` of a `redditads` connection and an `adAccountId` like `a2_abc123`. Zernio creates a campaign, an ad group carrying the budget, schedule, targeting and pixel, and an ad running a new promoted post. The post is authored by the ad account's first profile (422 when it has none).\n\nThe creative format follows the body:\n\n- `carouselCards`: a carousel.\n- `video`: a video ad.\n- `imageUrl`: an image ad.\n- None of them: a text ad, which cannot link out (`linkUrl` is a 400 there; `body` is required).\n\nOnly the legacy single-creative shape is available: `creatives[]`, `adSetId`, `existingCampaignId` and `validateOnly` are refused.\n\nReddit throttling surfaces as 429 `rate_limited` with `platform: reddit`; retry after a delay. To promote an existing Reddit post, use POST /v1/ads/boost.\n\n### Microsoft Ads\n\nUse the `accountId` of a `microsoftads` connection and its numeric `adAccountId`. Zernio creates a Search campaign carrying the daily budget and the countries, an ad group carrying the schedule, a responsive search ad and the `keywords`.\n\n- `goal` is `traffic`; `budgetType` must be `daily`.\n- `headline`, `body` and `linkUrl` are required. `additionalHeadlines` and `additionalDescriptions` complete the ad to 3 to 15 headlines (30 characters) and 2 to 4 descriptions (90 characters); missing ones are filled from `name` and the link's host.\n- `countries` (or `targeting.countries`) is required; no other targeting field applies.\n- Bid fields, `negativeKeywords`, `campaignNegativeKeywords`, sitelinks, callouts, structured snippets, `businessName`, `longHeadline` and a `campaignType` other than `search` return 422.\n\nWithout `status`, every level is switched on and the campaign spends once Microsoft approves the ad: send `status: PAUSED` to create it paused. A failed step deletes the campaign the call created.\n\n### Idempotency\n\nThis endpoint is not idempotent at the platform level: a blind retry creates a second campaign/ad set/ad. Send an `Idempotency-Key` header to make retries safe.\n\n- The first request with a given key creates the ad and we store the response.\n- A retry with the same key replays that exact response (with `Idempotent-Replayed: true`) instead of creating duplicates.\n- Reusing a key with a different body returns 422.\n- A key whose first request is still in flight returns 409 (retry after a short backoff).\n- If the first request is cut off mid-create (for example by a function timeout), its key can stay in progress and keep returning 409 until it expires. Use a new key to retry sooner, after checking whether the ad was created.\n- Keys are scoped to your credential and expire after 24h.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","adAccountId"],"properties":{"accountId":{"type":"string"},"adAccountId":{"type":"string"},"name":{"type":"string","maxLength":255,"description":"Omitted, the ad is named `Ad <YYYY-MM-DD HH:MM:SS>` (UTC) and the response reports it in `appliedDefaults.name`."},"campaignName":{"type":"string","maxLength":255,"description":"Meta, Reddit and Google. Exact campaign name; overrides the default `<name> - Campaign`. Ignored when the request joins an existing campaign or ad set.\n\nGoogle: no line breaks and at most 255 characters, checked before calling Google. Names are unique in the Google Ads account, and on Search and Display a taken name is a 400 naming this field."},"adSetName":{"type":"string","maxLength":255,"description":"Exact ad set name. Meta, Reddit and Google (the ad group).\n\n- Overrides the default `<name> - Ad Set` (Google Search and Display: `<name> - Ad Group`).\n- Ignored when the request joins an existing ad set (`adSetId`).\n- Google Search and Display only: also works on `existingCampaignId`, where the new ad group's name is returned as `adSetName`. No line breaks, at most 255 characters, unique in the campaign (a taken name is a 400 naming this field).\n- Demand Gen names its ad group with `demandGen.adGroupName`, and Performance Max with `assetGroup.name`.\n- For per-ad names on the multi-creative shape, set `name` on each `creatives[]` entry."},"adName":{"type":"string","maxLength":255,"description":"Meta only. Exact ad name, overriding the default `name`. On the multi-creative shape it names every ad, numbered `#1`, `#2`... when there are several, unless a `creatives[]` entry sets its own `name`."},"tracking":{"$ref":"#/components/schemas/AdTracking"},"goal":{"type":"string","enum":["engagement","traffic","awareness","video_views","lead_generation","lead_conversion","conversions","app_promotion","catalog_sales","page_likes","page_visits","job_applicants"],"description":"The ad's goal. Available goals vary by platform. When omitted, it is inferred from the ad (see `appliedDefaults.goal` in the response); the attach shape inherits it from the ad set.\n\n**Meta**\n\n- `conversions`: OUTCOME_SALES. Requires `promotedObject.pixelId` and `promotedObject.customEventType` with a commerce event (e.g. PURCHASE, START_TRIAL). Alternatives: `promotedObject.customConversionId` for a Custom Conversion, or `customEventType: OTHER` + `customEventStr` for a pixel custom event.\n- `lead_conversion`: OUTCOME_LEADS optimizing website pixel leads. Same pixel and event fields, with a leads-class event (LEAD, SUBMIT_APPLICATION, SCHEDULE, CONTACT) or `promotedObject.customConversionId`. Meta gates conversion events by objective, so leads-class events are rejected under `conversions`.\n- `lead_generation`: OUTCOME_LEADS with instant forms. Requires `leadGenFormId`. `promotedObject.pageId` is optional and auto-filled from the connected Page.\n- `app_promotion`: requires `promotedObject.applicationId` and `promotedObject.objectStoreUrl`.\n- `catalog_sales`: Advantage+ catalog ads (e.g. vehicle inventory). Requires `promotedObject.productSetId`, `promotedObject.pixelId` and `promotedObject.customEventType`. Builds a catalog TEMPLATE creative from the copy fields, which may carry template tags like {{product.name}} or {{vehicle.make}}.\n- `catalog_sales` visuals: no imageUrl or video is sent; Meta renders them per catalog item (an imageUrl or video sent is ignored, not uploaded). Find catalogs via GET /v1/ads/catalogs and product sets via GET /v1/ads/catalogs/{catalogId}/product-sets.\n- `catalog_sales` shape: single shape only, no creatives[], dynamicCreative, placementAssets, existingCreativeId or carouselCards. Works with `existingCampaignId`, and with `adSetId` to add to an existing ad set (then only `promotedObject.productSetId` is required). Pick the format with `catalogFormat`, and open the carousel with `catalogIntroCards`.\n- `traffic` with `promotedObject.productSetId`: a catalog ad without a pixel (OUTCOME_TRAFFIC, `optimizationGoal` LINK_CLICKS by default or LANDING_PAGE_VIEWS). The product set goes on the template creative only, never the ad set's promoted_object. No `pixelId` or `customEventType` needed. Same creative rules as `catalog_sales`.\n- `page_likes`: Page Likes under OUTCOME_ENGAGEMENT (destination_type ON_PAGE, optimization PAGE_LIKES). `promotedObject.pageId` is optional and auto-filled. The CTA is fixed to LIKE_PAGE for that Page; headline / body / linkUrl / callToAction / imageUrl / video are all optional (Meta derives them from the Page).\n- `page_visits`: \"Page visits and followers\" under OUTCOME_TRAFFIC (destination_type FACEBOOK_PAGE, optimization PROFILE_VISIT). `promotedObject.pageId` is optional and auto-filled; `linkUrl` defaults to the Page. Accounts Meta has not enabled are refused with \"This account isn't eligible to use Profile Visit ads yet\".\n\n**TikTok**\n\n- `conversions`: website-conversion ad group. Requires `promotedObject.pixelId` (your TikTok Pixel ID). Optional `promotedObject.customEventType`: a TikTok optimization_event code your pixel tracks (newer pixels: e.g. SHOPPING for purchases; legacy: ON_WEB_ORDER, INITIATE_ORDER, ON_WEB_REGISTER, FORM). To inherit pixel and event from an existing ad group, pass `adSetId`.\n\n**LinkedIn**\n\n- `engagement`, `traffic`, `awareness`, `video_views`: standalone Direct Sponsored Content ads. `traffic` requires `linkUrl`; `video_views` requires `video`.\n- `lead_generation`: requires `leadGenFormId` (an adForm ID from POST /v1/ads/lead-forms). Sets the campaign objective to MAX_LEAD and the creative's `leadgenCallToAction` destination to `urn:li:adForm:{id}`.\n- `job_applicants`: requires a `platformSpecificData.jobs` creative.\n- `conversions` or promoting an existing post: use POST /v1/ads/boost.\n\n**OpenAI Ads**\n\n- Only `traffic`, `awareness`, `conversions` (other goals return 400). They map to OpenAI's `bidding_type` (clicks, impressions, conversions).\n- `conversions` needs an active conversion event setting on the account, or returns 400. Create a tracking tag with `defaultEventType` (`POST /v1/accounts/{accountId}/tracking-tags`) or configure one in OpenAI Ads Manager.\n- Pick the event with `promotedObject.customEventType` (see AdPromotedObject); without it, the most recently created optimizable event is used.\n\n**Reddit Ads**\n\n- Supported: `traffic` (CLICKS), `awareness` (BRAND_AWARENESS), `conversions`, `video_views` (VIDEO_VIEWABLE_IMPRESSIONS), `lead_generation` (LEAD_GENERATION). Any other goal returns 400.\n- `conversions`: requires `promotedObject.customEventType`; the pixel must already have received that event (see AdPromotedObject).\n- `lead_generation`: sends people to `linkUrl` and optimizes toward the pixel's Lead event, which the pixel must already have received. Reddit retired native lead forms on September 30, 2026, so `leadGenFormId` returns 400.\n- `video_views`: needs a `video` (422 otherwise); `optimizationGoal` picks VIDEO_VIEW_6S (default) or VIDEO_VIEW_15S.\n"},"smartTargeting":{"type":"object","description":"TikTok only (a 400 elsewhere). TikTok Smart Targeting on the ad group. When on, TikTok may deliver beyond the selected audiences or interests.\n\n- `audience`: TikTok's `smart_audience_enabled`.\n- `interestsBehaviors`: TikTok's `smart_interest_behavior_enabled`.\n\nAvailable on Video views, Traffic, Lead generation, App install, Web conversion and Community interaction. Not available with smartPlus or when attaching to an existing ad set (adSetId).\n\nOnly the flags you send are written. An unwritten flag reads back null in `nativeSettings`, so send `false` explicitly to be able to verify it is off.\n","properties":{"audience":{"type":"boolean","description":"TikTok smart_audience_enabled."},"interestsBehaviors":{"type":"boolean","description":"TikTok smart_interest_behavior_enabled."}}},"optimizationGoal":{"type":"string","description":"Explicit optimization goal. Supported on:\n\n- **TikTok** with goal video_views: ENGAGED_VIEW (the 6-second default) or ENGAGED_VIEW_FIFTEEN; both bill per view.\n- **Reddit** with goal video_views: VIDEO_VIEW_6S (default) or VIDEO_VIEW_15S; other values return 400.\n- **Meta:** the ad-set `optimization_goal` (e.g. `LANDING_PAGE_VIEWS`, `LINK_CLICKS`, `REACH`, `IMPRESSIONS`, `OFFSITE_CONVERSIONS`, `THRUPLAY`, `LEAD_GENERATION`).\n\nOn Meta it overrides the default derived from `goal` (e.g. `traffic` defaults to `LINK_CLICKS`). It is forwarded verbatim; Meta validates compatibility with the campaign objective and rejects incompatible combinations."},"billingEvent":{"type":"string","description":"Meta only. Explicit ad-set `billing_event`. Defaults to `IMPRESSIONS`. Forwarded verbatim to Meta, which validates compatibility with the optimization goal."},"buyingType":{"type":"string","enum":["AUCTION","RESERVED"],"default":"AUCTION","description":"Meta only. Buying type. Defaults to AUCTION and is explicitly sent on new campaigns, including validateOnly. Reusing existingCampaignId does not change the campaign.\n\nRESERVED = Reach & Frequency:\n\n- Requires `rfPredictionId` (a RESERVED prediction from /v1/ads/rf-predictions + /reserve).\n- Budget, schedule and pricing come from the reservation, so budgetAmount/budgetType are not required and bid fields are ignored.\n- Only the plain single-ad shape (no creatives[], adSetId, existingCampaignId or dynamicCreative)."},"rfPredictionId":{"type":"string","description":"Meta only. The RESERVED prediction id the R&F ad set runs on (reserving mints a new id, so pass that one). Requires buyingType RESERVED."},"promotion":{"$ref":"#/components/schemas/MetaPromotion","description":"Not supported. Meta validates creative_sourcing_spec.promotion_metadata_spec on the create call and then discards it, so a Promotion set through the Marketing API never reaches the creative.\n\nAny object is rejected with 400 invalid_field_value. Send null or omit the field, and set the Promotion on the ad in Ads Manager. Verified on 2026-09-11 across Graph v19.0 to v25.0 and every write path.\n"},"creativeFeatures":{"$ref":"#/components/schemas/MetaCreativeFeatures","description":"Meta only. Applied to each new creative, including standalone, attach and catalog template shapes.\n\n- With creatives[], these are defaults; an item replaces the whole feature map, including an empty map.\n- auto_promotion_tag is an Advantage+ enhancement, not the Ads Manager Promotion setting.\n- On catalog ads, the catalog enhancements are keys of this same map, for example `{ \"product_extensions\": \"OPT_OUT\", \"media_type_automation\": \"OPT_OUT\", \"standard_enhancements_catalog\": \"OPT_OUT\", \"multi_creative_post_carousel\": \"OPT_OUT\" }`.\n"},"catalogFormat":{"type":"string","enum":["single_image","carousel_images_multi_items","carousel_images_single_item","carousel_slideshows"],"description":"Meta catalog template creatives only (goal `catalog_sales`, goal `traffic` with `promotedObject.productSetId`, or `adSetId` with `promotedObject.productSetId`); a 400 otherwise. Omit it to let Meta pick the format.\n\nSent as `object_story_spec.template_data.format_option`. `force_single_link` is never sent with it (Meta rejects the pair, subcode 1443051).\n\n- `single_image`: also sends `format_transformation_spec` with `carousel` and `da_collection` set to `data_source: [\"none\"]`, so Meta keeps the single image instead of turning it into a carousel or collection.\n- `carousel_images_single_item`: also sends `template_data.multi_share_end_card: false`, which Meta requires for that format (subcode 1443167).\n"},"catalogIntroCards":{"type":"array","minItems":1,"maxItems":3,"description":"Meta only. Static cards shown before the catalog products in a catalog carousel, for example a brand or offer slide. Valid only with goal `catalog_sales` and `catalogFormat` omitted or `carousel_images_multi_items`; a 400 otherwise.\n\nSent in order as `object_story_spec.template_data.child_attachments` with `static_card: true`, followed by one catalog card built from the top-level `headline`, `description` and `callToAction`.\n","items":{"type":"object","required":["imageUrl","headline"],"properties":{"imageUrl":{"type":"string","format":"uri","description":"Card image; uploaded to the ad account and referenced by hash."},"headline":{"type":"string","minLength":1,"maxLength":255,"description":"Card headline. Meta does not show it on Instagram."},"description":{"type":"string","maxLength":255,"description":"Card description. Meta does not show it on Instagram."},"linkUrl":{"type":"string","format":"uri","description":"Card destination URL. Defaults to the top-level linkUrl."},"callToAction":{"type":"string","description":"Card CTA override. Defaults to the top-level callToAction; same enum."}}}},"multiAdvertiser":{"type":"string","enum":["OPT_IN","OPT_OUT"],"description":"Meta only. Multi-advertiser ads: whether Meta may show this ad alongside other advertisers' in one unit. Meta auto-enrols since Aug 2024, so send OPT_OUT to leave. It is a top-level creative field, NOT a `creativeFeatures` key, and Meta rejects it there."},"aiDisclosure":{"type":"string","enum":["OPT_IN","OPT_OUT"],"description":"Meta only. Meta's \"Ad includes media created or edited with AI\" disclosure (the Ads Manager checkbox), stored on the creative as `generative_asset_spec.transparency_metadata.self_disclosure`.\n\n- OPT_IN: checks it.\n- OPT_OUT: explicitly declares no AI media.\n- Omitted: leaves Meta's default.\n\nApplied to each new creative (standalone, creatives[] and attach shapes) and preserved when a creative is rebuilt. This sets the disclosure on the ad; whether and when the viewer-facing label renders is Meta's decision.\n"},"retryOnServerError":{"type":"boolean","description":"Meta only (a 400 elsewhere). When Meta answers a create with a 5xx and reading the parent back by name finds no such object, Zernio sends the create again (at most 3 POSTs per object, never for an object created ACTIVE) and reports it in `recoveredWrites`.\n\n`false` never sends it again: the request fails with 502 and `details.unconfirmedWrite`, so you can check the parent yourself. One object found by name is still reused.\n"},"validateOnly":{"type":"boolean","description":"Validate the request without creating anything. Supported on Meta, TikTok, ChatGPT (OpenAI) and Google Performance Max / Demand Gen. Any other platform, or a Google campaignType other than pmax or demand_gen, returns 501 `feature_not_available`.\n\n**Google Performance Max**: validates the complete atomic campaign and asset group, with no resource creation or local persistence. Validation still downloads image URLs and consumes quota.\n\n**Meta**: validates the inline campaign, ad set, creative and ad with execution_options validate_only. Nothing is uploaded or created; validation bypasses Idempotency-Key storage. Success returns 200 with per-node results; a Meta rejection returns an error.\n\nBefore the dry run, Meta validateOnly runs the account status and payment checks of GET /v1/ads/accounts/health: an ad account that is not ready answers its blocker `code` (`ad_account_unusable`, `ad_account_payment_required`) with `details.hint` and `details.fix`, and Meta is not called.\n\n- Supported: a single image or existing video.id (each also with bodies[] / headlines[] Multiple Text Options), all-image placementAssets with per-rule copy and text pools, placementAssets with an existing video id in every slot and no thumbnails, or existingCreativeId.\n- Return 400: dynamicCreative, translations, carouselCards, placement videos by URL or with thumbnails, new video uploads, creatives[], adSetId, RESERVED buying.\n- Placement validation uses existing Instagram identities only. Existing campaign or creative nodes are marked skipped.\n- When Meta cannot dry-run the nested tree, the campaign and creative are validated alone and the adSet and ad nodes return unverified with the reason. This covers code 2, and two errors Meta returns but then creates normally (below).\n- Code 1 (unknown error) on an OFFSITE_CONVERSIONS ad set nested in a new campaign (some website-conversion ad sets).\n- Code 100 subcode 2446880 \"WhatsApp number required\" on an ad that does not message on WhatsApp (intermittent). If the creative's own dry run also asks for a WhatsApp number, the creative is unverified too. Messaging ads still fail on 2446880.\n\n**ChatGPT (OpenAI)**: no platform dry-run. Zernio runs every check it knows (creative lengths, budget, bid strategy, targeting) plus live lookups of the conversion event and target countries, and uploads or creates nothing. OpenAI's own checks (image fetch, currency-specific minimums, ad review) run only on a real create.\n\n**TikTok**: TikTok has no dry-run. Zernio runs the input checks and the read-only TikTok calls a real create makes. It uploads or creates nothing: no video, Brand Identity, campaign, ad group or ad. A failure returns the same 4xx a real create would.\n\n- Advertiser: `message` names its currency when TikTok returns it.\n- Identity: `identityId` is authorized on the advertiser (the `identity` node). `message` names the identity and type the ad would run as.\n- `existingCampaignId`: exists and is not an Upgraded Smart+ campaign.\n- Pixel and optimization event resolve on the advertiser, and the schedule and targeting build.\n- Not checked (marked `unverified` with the reason): the video (format, size, length, cover), the ad group as TikTok would create it (the budget minimum for the advertiser currency, location and audience ids, bid), a new campaign, and TikTok's review of the ad text, call to action and landing page.\n- A Brand Identity a real create would make from `brandIdentity` is not made: the `identity` node is `unverified`.\n- Supported: the single standalone video ad. `smartPlus` and `adSetId` return 400.\n"},"budgetAmount":{"type":"number","description":"Budget in WHOLE currency units (USD: 50 = $50.00), NOT cents. Meta's own Marketing API takes this number in minor units, an easy and expensive mix-up.\n\nRequired on legacy, multi-creative and Performance Max shapes. Inherited on attach.\n\n**OpenAI Ads:** in the ad account currency, minimum 1. OpenAI can require a higher daily minimum for some currencies and names it in the error."},"budgetType":{"type":"string","enum":["daily","lifetime"],"description":"Defaults to daily when `budgetAmount` is sent without it (reported in `appliedDefaults.budgetType`). Inherited on attach.\n\n- **OpenAI Ads:** accepts both as the campaign's single spend cap. A lifetime cap can later switch to daily with PUT /v1/ads/campaigns/{campaignId}, but never daily back to lifetime (422). Automatic bidding (Maximize Results) needs a daily budget.\n- **Reddit Ads:** the ad group's daily or lifetime spend goal."},"status":{"type":"string","enum":["ACTIVE","PAUSED"],"description":"Publish state of the created entities, on every platform. Omitted or ACTIVE publishes live (default, back-compat).\n\nPAUSED pauses only the TOP-MOST object this call creates and switches everything below it on, so one resume of that object brings the new tree live and nothing pre-existing is touched:\n\n- New campaign: held paused with its ad set and ad on.\n- With `existingCampaignId`: the new ad set is held paused with its ad on.\n- With `adSetId`: the new ad itself is paused.\n\n**Level overrides.** `campaignStatus`, `adSetStatus` and `adStatus` set one level each and always win for that level. `status: PAUSED` adds its own hold only when none of them is PAUSED. `campaignStatus: ACTIVE` with `status: PAUSED` moves the pause down to the new ad set. To create every object paused, send all three as PAUSED.\n\n**Platform notes:**\n\n- LinkedIn: every object the call creates is held. A new campaign group is PAUSED. A new campaign or creative stays DRAFT, as LinkedIn refuses PAUSED on a creative until its review is APPROVED. Resume each held object top-down to go live.\n- X: no per-ad switch, so its lowest level is the line item.\n- Google Performance Max and Demand Gen: accept PAUSED only (the campaign is created paused).\n"},"campaignStatus":{"type":"string","enum":["ACTIVE","PAUSED"],"description":"Every platform. Sets the switch of the new campaign alone (LinkedIn: the campaign group) and overrides `status` for it. Omitted, it follows `status`. Ignored when the request creates no campaign (`existingCampaignId` or `adSetId`).\n\n- `PAUSED`: holds the campaign off with its ad set and ad on, unless `adSetStatus` or `adStatus` say otherwise.\n- `ACTIVE` with `status: PAUSED`: switches the campaign on and holds the new ad set paused (its ad on).\n"},"adSetStatus":{"type":"string","enum":["ACTIVE","PAUSED"],"description":"Every platform. Sets the switch of the new ad set alone and overrides `status` for it. When omitted, it follows `status`. Equivalent object: Google, TikTok, Pinterest and ChatGPT, the ad group; LinkedIn, the campaign (stays DRAFT when held); X, the line item.\n\nPrecedence: a level status (`campaignStatus`, `adSetStatus`, `adStatus`) always wins for its level. `status: PAUSED` then holds the top-most new object with no level status, only when no level status is PAUSED. Every other new object is switched on.\n\nSo `campaignStatus: ACTIVE` + `adSetStatus: PAUSED` + `adStatus: PAUSED` keeps the campaign on with the new ad set and ad off; all three PAUSED creates the whole tree paused.\n\nRejected with a 400 alongside `adSetId` (that ad set exists; change it with PUT /v1/ads/ad-sets/{adSetId}/status). Performance Max and Demand Gen accept PAUSED only.\n"},"adStatus":{"$ref":"#/components/schemas/AdActivationStatus","description":"Sets the switch of the new ad alone, also when attaching to an existing ad set with `adSetId`, and overrides `status` for it. Same precedence as `adSetStatus`. Omitted, it follows `status`.\n\n- LinkedIn: a creative held off is created DRAFT, because LinkedIn refuses PAUSED on a creative until its review is APPROVED. A DRAFT creative is not submitted for review and cannot serve; it reads `paused`. Resuming the ad (PUT /v1/ads/{adId}/status `active`) switches it ACTIVE, which starts the review.\n- X: returns a 400. A promoted post has no switch of its own, so hold the line item with `adSetStatus`.\n- `PAUSED` with `buyingType: RESERVED`: returns a 400 (Meta creates the first Reach and Frequency ad ACTIVE).\n- Performance Max and Demand Gen: accept PAUSED only.\n"},"budgetLevel":{"type":"string","enum":["adset","campaign"],"description":"Meta only. Where the budget lives, which selects the Meta budget model:\n\n- `adset` (used when omitted): ABO (Ad-set Budget Optimization). The budget is set on the ad set.\n- `campaign`: CBO (Campaign Budget Optimization / Advantage Campaign Budget). The budget AND `bidStrategy` are set on the CAMPAIGN, and Meta distributes spend across ad sets automatically.\n\nThe returned ad stores the applied `budgetLevel`, and the budget in `campaignBudget` (CBO) or `adSetBudget` (ABO). Edit CBO budgets with `PUT /v1/ads/campaigns/{campaignId}` and ABO budgets with `PUT /v1/ads/ad-sets/{adSetId}`.\n\nMeta requires the budget at exactly one level, never both. Ignored on the Meta attach shape (`adSetId`), which inherits the existing budget.\n\nGoogle Demand Gen also reads it. A new Demand Gen campaign accepts only `campaign` or no value. With `existingCampaignId` or `adSetId`, omit it: the budget stays on the existing campaign. Other platforms ignore it.\n"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code matching the ad account's currency (e.g. `USD`). Meta only. Optional: Zernio resolves it from the ad account when omitted. The value selects the minor-unit exponent Zernio converts budget/bid amounts by before calling Meta (most currencies are cents; zero-decimal currencies like JPY/KRW are sent as-is)."},"headline":{"type":"string","description":"Ad headline. Required for Meta, Google, Pinterest, LinkedIn, OpenAI Ads and Reddit Ads on legacy + attach shapes (for multi-creative, skip it and use `creatives[].headline`). Ignored for TikTok.\n\nMax length: Meta=255, Google=30, Pinterest=100, LinkedIn=400, OpenAI=50 (min 3), Reddit=300.\n\n- LinkedIn: the ad's headline (the bold text on the creative); for traffic ads, the link card title.\n- OpenAI Ads: the chat card's title.\n- Reddit: the promoted post's title.\n- X: the website card title (needs imageUrl and linkUrl, max 70)."},"longHeadline":{"type":"string","maxLength":90,"description":"Google Display only. Defaults to `headline` if omitted. On LinkedIn, reused as the optional secondary description text on traffic (link) ads; omitted if not provided."},"body":{"type":"string","description":"Required on legacy + attach shapes.\n\n- X: the tweet text (max 280 chars including a ~24-char URL when `linkUrl` is set).\n- LinkedIn: the post commentary (the intro text shown above the ad).\n- OpenAI Ads: the chat card's body text.\n- Reddit: the promoted post's body. Optional on image, video and carousel ads, required on text ads.\n\nMax: Google=90, Pinterest=500, OpenAI=100."},"description":{"type":"string","maxLength":255,"description":"Meta only (facebook/instagram). Link description: the secondary text shown below the headline (Meta's link_data.description; on video creatives mapped to video_data.link_description). When omitted, Meta auto-pulls the destination URL's OpenGraph description.\n\n- Applies on legacy, attach, and placementAssets shapes.\n- For multi-creative use creatives[].description (this field is the shared fallback).\n- For multi-text variations use `descriptions` (array) instead."},"bodies":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string"},"description":"Meta only. Multiple Text Options (Advantage+ Flexible Format): 1-5 primary-text variations that Meta optimises delivery across, WITHOUT enabling full Dynamic Creative (`dynamicCreative`).\n\nUses `optimization_type: DEGREES_OF_FREEDOM` on the asset feed, so multiple ads per ad set are allowed (unlike `dynamicCreative`, which is limited to one).\n\n**Requirements:** `imageUrl` or `video`, `linkUrl`, `callToAction`, and `headlines`. The top-level `body` becomes `object_story_spec.link_data.message` (the preview text). On a video creative the copy lands in `video_data.message` / `video_data.title` instead of `link_data`.\n\nMutually exclusive with `dynamicCreative`, `carouselCards`, and `creatives[]`.\n\n**With `placementAssets`:** the pool applies to the placement-customized creative instead (`optimization_type: PLACEMENT`). Every body carries the label of each rule that does not pin its own `body` (same for `headlines`), so Meta rotates options per placement while media stays pinned.\n\nA rule's own `body` / `headline` stays pinned for that placement. `descriptions[]` cannot join a placement-customized creative (Meta refuses a second description per rule, subcode 1885878).\n"},"headlines":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string","maxLength":255},"description":"Meta only. Headline variations for Multiple Text Options. Must be sent alongside `bodies`.\nThe top-level `headline` field is used as the `object_story_spec.link_data.name`\n(`video_data.title` on a video creative).\n"},"descriptions":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string","maxLength":255},"description":"Meta only. Optional description variations for Multiple Text Options. Sent alongside `bodies` and `headlines`."},"callToAction":{"type":"string","enum":["BOOK_TRAVEL","CONTACT_US","DONATE","DONATE_NOW","DOWNLOAD","GET_DIRECTIONS","GO_LIVE","INTERESTED","LEARN_MORE","SEE_DETAILS","LIKE_PAGE","MESSAGE_PAGE","RAISE_MONEY","SAVE","SEND_TIP","SHOP_NOW","SIGN_UP","VIEW_INSTAGRAM_PROFILE","INSTAGRAM_MESSAGE","LOYALTY_LEARN_MORE","PURCHASE_GIFT_CARDS","PAY_TO_ACCESS","SEE_MORE","TRY_IN_CAMERA","WHATSAPP_LINK","GET_IN_TOUCH","TRY_NOW","ASK_A_QUESTION","START_A_CHAT","CHAT_NOW","ASK_US","CHAT_WITH_US","SHOP_ON_RETAILER","BOOK_NOW","CHECK_AVAILABILITY","ORDER_NOW","WHATSAPP_MESSAGE","GET_MOBILE_APP","INSTALL_MOBILE_APP","USE_MOBILE_APP","INSTALL_APP","USE_APP","PLAY_GAME","TRY_DEMO","WATCH_VIDEO","WATCH_MORE","OPEN_LINK","NO_BUTTON","LISTEN_MUSIC","MOBILE_DOWNLOAD","GET_OFFER","GET_OFFER_VIEW","BUY_NOW","BUY_TICKETS","UPDATE_APP","BET_NOW","ADD_TO_CART","SELL_NOW","GET_SHOWTIMES","LISTEN_NOW","GET_EVENT_TICKETS","REMIND_ME","SEARCH_MORE","PRE_REGISTER","SWIPE_UP_PRODUCT","SWIPE_UP_SHOP","PLAY_GAME_ON_FACEBOOK","VISIT_WORLD","OPEN_INSTANT_APP","JOIN_GROUP","GET_PROMOTIONS","SEND_UPDATES","INQUIRE_NOW","VISIT_PROFILE","CHAT_ON_WHATSAPP","EXPLORE_MORE","CONFIRM","JOIN_CHANNEL","MAKE_AN_APPOINTMENT","ASK_ABOUT_SERVICES","BOOK_A_CONSULTATION","GET_A_QUOTE","BUY_VIA_MESSAGE","ASK_FOR_MORE_INFO","VIEW_PRODUCT","VIEW_CHANNEL","WATCH_LIVE_VIDEO","JOIN_LIVE_VIDEO","IMAGINE","WATCH_NOW","STREAM_NOW","BUY_ACTIVITY_TICKETS","CALL","MISSED_CALL","CALL_NOW","CALL_ME","APPLY_NOW","BUY","GET_QUOTE","SUBSCRIBE","RECORD_NOW","VOTE_NOW","GIVE_FREE_RIDES","REGISTER_NOW","OPEN_MESSENGER_EXT","EVENT_RSVP","CIVIC_ACTION","SEND_INVITES","REFER_FRIENDS","REQUEST_TIME","SEE_MENU","SEARCH","TRY_IT","TRY_ON","LINK_CARD","DIAL_CODE","FIND_YOUR_GROUPS","START_ORDER","REGISTER","JOIN","ATTEND","REQUEST_DEMO","VIEW_QUOTE","APPLY"],"description":"The ad's call-to-action button.\n\n- **Meta:** required on legacy + attach shapes. Accepts every call to action type Meta itself accepts (the enum lists them), including values such as SEE_DETAILS that ads synced from Meta carry.\n- **TikTok:** honoured, passed through to the Spark Ad creative's `call_to_action`.\n- **LinkedIn:** the CTA button on the ad; defaults to LEARN_MORE when `linkUrl` is set. Accepts LEARN_MORE, SIGN_UP, DOWNLOAD, SUBSCRIBE, REGISTER, JOIN, ATTEND, REQUEST_DEMO, VIEW_QUOTE, APPLY, SEE_MORE, SHOP_NOW, BUY_NOW.\n- **Reddit** (image, video and carousel ads): accepts LEARN_MORE, SHOP_NOW, SIGN_UP, CONTACT_US, DOWNLOAD, GET_QUOTE, SUBSCRIBE, APPLY_NOW, BOOK_NOW, BUY_TICKETS, DONATE_NOW, GET_DIRECTIONS, GET_SHOWTIMES, LISTEN_NOW, ORDER_NOW, SEE_MENU, INSTALL_MOBILE_APP. Other values return 400.\n- **Google, Pinterest, and X:** ignored."},"linkUrl":{"type":"string","format":"uri","description":"The ad's destination URL. Required on legacy + attach shapes (skip for multi-creative). NOT required when `goal` is `lead_generation` (the ad opens a Lead Gen form instead).\n\n- **LinkedIn:** required for `traffic` ads, optional for `engagement` / `awareness`. `imageUrl` + `linkUrl` publishes an ARTICLE-content creative (LinkedIn's article ad format), with the image as thumbnail and `longHeadline` as description.\n- **OpenAI Ads:** required (the chat card's target_url).\n- **Reddit:** required on image and video ads (the post's destination and the ad's click URL), the fallback for carousel cards without their own, and refused with 400 on text ads."},"leadGenFormId":{"type":"string","description":"Lead Gen form ID to attach to the ad's creative. REQUIRED when `goal` is `lead_generation`. Create one via POST /v1/ads/lead-forms.\n\n- Meta (facebook/instagram): the leadgen_forms ID. The ad set's promoted_object.page_id, LEAD_GENERATION optimization and destination_type ON_AD are derived automatically from the goal.\n- Meta: also required on every ATTACH (`adSetId`) call targeting a lead ad set (the form attaches per-ad; Meta rejects a formless ad in a lead ad set).\n- Meta: `placementAssets`, `dynamicCreative` and `carouselCards` (multi-card Instant-Form lead ad) ARE supported on instant-form lead ads. `linkUrl` and per-card `linkUrl` are optional, forwarded as real destinations when sent, else falling back to Meta's lead-form link.\n- LinkedIn: the adForm ID. The creative's `leadgenCallToAction.destination` is set to `urn:li:adForm:{id}` and the campaign objective to MAX_LEAD. Forms must be owned by the sponsoredAccount (not the organization) for the URN to resolve.\n- Reddit: rejected with 400 on every goal (Reddit retired its native lead forms)."},"imageUrl":{"type":"string","format":"uri","description":"Image creative for Meta/Google/Pinterest/LinkedIn on legacy + attach shapes. Mutually exclusive with `video`.\n\n- LinkedIn: required unless `video` is set. Uploaded to LinkedIn under the authoring Company Page (see `organizationId`); recommended ratio 1.91:1 (e.g. 1200×627).\n- Google: not required for Search campaigns. For Display, treated as the landscape image (alias of `images.landscape`); supply `images.square` alongside or the request is rejected.\n- TikTok: this field carries the VIDEO URL (the TikTok ads endpoint is video-only; the `imageUrl` name is kept for cross-platform consistency).\n- X: imageUrl + headline + linkUrl together build a website card (image, title and destination under the post; the URL is not added to the post text). Sending only some of them is a 400.\n- X: description, video and callToAction are rejected with 400 (promote a post that carries a video with POST /v1/ads/boost).\n- OpenAI Ads: required, uploaded as the chat card's image (OpenAI has no video ad format).\n- Reddit: builds an image ad (requires `linkUrl`). On a Reddit video ad it is the fallback for `video.thumbnailUrl`."},"images":{"type":"object","description":"Google Display (Responsive Display Ads) only. Google RDA requires both a landscape (1.91:1) and a square (1:1) marketing image; sending only one is rejected upstream as 'Too few.' (NOT_ENOUGH_*_MARKETING_IMAGE_ASSET). Supply both URLs here.\n\nEither this field or the legacy `imageUrl` can provide the landscape, but `square` has no legacy counterpart, so it must be set here for Display.\n","properties":{"landscape":{"type":"string","format":"uri","description":"Landscape 1.91:1 marketing image URL (e.g. 1200x628). Also accepted via the top-level `imageUrl` for backward compatibility."},"square":{"type":"string","format":"uri","description":"Square 1:1 marketing image URL (e.g. 1080x1080). Required for Google Display."}}},"video":{"type":"object","description":"Creates a single VIDEO ad. Meta (facebook, instagram), LinkedIn and Reddit. Mutually exclusive with `imageUrl`.\n\nSupply `url` to upload a file, or `id` to reuse a video already on the ad account (list them with GET /v1/ads/videos). Works on the single-ad and attach (`adSetId`) shapes; for Meta multi-creative, set `video` per entry inside `creatives[]` instead. Supply MP4 H.264/AAC, 3s-30min, 75KB-500MB.\n\n- Reddit: `url`, `linkUrl` and a thumbnail (`thumbnailUrl`, or `imageUrl`) are all required.\n- LinkedIn: uploaded under the authoring Company Page (see `organizationId`) and the campaign format is set to SINGLE_VIDEO. LinkedIn ignores `thumbnailUrl` (it auto-generates the poster frame).\n","properties":{"url":{"type":"string","format":"uri","description":"Public URL of the video. Meta: uploaded via chunked transfer on /act_X/advideos, then the request blocks on Meta's transcoding until status.video_status === 'ready'. LinkedIn: uploaded via the Videos API (multipart), then the request blocks until LinkedIn finishes transcoding (status AVAILABLE); short clips take ~10-30s. Provide either `url` or `id`."},"id":{"type":"string","description":"Meta only. Reuse a video ALREADY uploaded to this ad account instead of re-uploading the file: pass the `videoId` returned by a previous create. Wins over `url`, so N ads that differ only in copy share one upload (`existingCreativeId` only covers the identical-copy case). Provide either `url` or `id`."},"thumbnailUrl":{"type":"string","format":"uri","description":"Public URL of a still-image thumbnail for the video. OPTIONAL.\n\n- Meta, omitted: the poster is auto-generated from Meta's own preferred video thumbnail (the candidates Ads Manager shows), so video ads usually publish without one. If Meta produces no candidate, the request fails with a 502 platform_error (reason: video_thumbnail_unavailable): retry, or supply this field.\n- Meta, provided: controls the poster frame exactly (uploaded as an ad image and referenced in object_story_spec.video_data).\n- LinkedIn: ignored (auto-generated poster frame)."}}},"creatives":{"type":"array","minItems":1,"maxItems":50,"description":"Meta-only. When present, switches to the multi-creative shape:\ncreates 1 campaign + 1 ad set + N ads (one per entry here).\nMutually exclusive with `adSetId`.\n\nWith `existingCampaignId` it creates 1 ad set + N ads under that campaign, so one call per\naudience launches a creative matrix.\n\nTop-level `headline` / `body` / `imageUrl` / `linkUrl` /\n`callToAction` are ignored in this mode. Entries that repeat an `imageUrl` or `video.url` share\none upload.\n","items":{"type":"object","required":["headline","body","linkUrl","callToAction"],"description":"Each creative must supply EXACTLY ONE of `imageUrl` (image creative) or `video` (video creative).","properties":{"creativeFeatures":{"$ref":"#/components/schemas/MetaCreativeFeatures","description":"Replaces the entire top-level creativeFeatures map for this item. Omit to inherit; an empty map clears these defaults."},"name":{"type":"string","maxLength":255,"description":"Exact name for this ad. Falls back to `<name> #N` (N = 1-based position)."},"headline":{"type":"string","maxLength":255},"body":{"type":"string"},"description":{"type":"string","maxLength":255,"description":"Link description for this ad (link_data.description; video creatives: video_data.link_description). Falls back to the top-level `description`; when both are omitted Meta scrapes the destination URL's OG description."},"imageUrl":{"type":"string","format":"uri","description":"Image creative. Mutually exclusive with `video`."},"video":{"type":"object","description":"Video creative for this entry. Mutually exclusive with `imageUrl`. thumbnailUrl is optional: when omitted, the poster is auto-generated from Meta's preferred video thumbnail, and the request fails with a 502 platform_error (reason: video_thumbnail_unavailable) if Meta produces no candidate.","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"thumbnailUrl":{"type":"string","format":"uri"}}},"linkUrl":{"type":"string","format":"uri"},"callToAction":{"type":"string","enum":["BOOK_TRAVEL","CONTACT_US","DONATE","DONATE_NOW","DOWNLOAD","GET_DIRECTIONS","GO_LIVE","INTERESTED","LEARN_MORE","SEE_DETAILS","LIKE_PAGE","MESSAGE_PAGE","RAISE_MONEY","SAVE","SEND_TIP","SHOP_NOW","SIGN_UP","VIEW_INSTAGRAM_PROFILE","INSTAGRAM_MESSAGE","LOYALTY_LEARN_MORE","PURCHASE_GIFT_CARDS","PAY_TO_ACCESS","SEE_MORE","TRY_IN_CAMERA","WHATSAPP_LINK","GET_IN_TOUCH","TRY_NOW","ASK_A_QUESTION","START_A_CHAT","CHAT_NOW","ASK_US","CHAT_WITH_US","SHOP_ON_RETAILER","BOOK_NOW","CHECK_AVAILABILITY","ORDER_NOW","WHATSAPP_MESSAGE","GET_MOBILE_APP","INSTALL_MOBILE_APP","USE_MOBILE_APP","INSTALL_APP","USE_APP","PLAY_GAME","TRY_DEMO","WATCH_VIDEO","WATCH_MORE","OPEN_LINK","NO_BUTTON","LISTEN_MUSIC","MOBILE_DOWNLOAD","GET_OFFER","GET_OFFER_VIEW","BUY_NOW","BUY_TICKETS","UPDATE_APP","BET_NOW","ADD_TO_CART","SELL_NOW","GET_SHOWTIMES","LISTEN_NOW","GET_EVENT_TICKETS","REMIND_ME","SEARCH_MORE","PRE_REGISTER","SWIPE_UP_PRODUCT","SWIPE_UP_SHOP","PLAY_GAME_ON_FACEBOOK","VISIT_WORLD","OPEN_INSTANT_APP","JOIN_GROUP","GET_PROMOTIONS","SEND_UPDATES","INQUIRE_NOW","VISIT_PROFILE","CHAT_ON_WHATSAPP","EXPLORE_MORE","CONFIRM","JOIN_CHANNEL","MAKE_AN_APPOINTMENT","ASK_ABOUT_SERVICES","BOOK_A_CONSULTATION","GET_A_QUOTE","BUY_VIA_MESSAGE","ASK_FOR_MORE_INFO","VIEW_PRODUCT","VIEW_CHANNEL","WATCH_LIVE_VIDEO","JOIN_LIVE_VIDEO","IMAGINE","WATCH_NOW","STREAM_NOW","BUY_ACTIVITY_TICKETS","CALL","MISSED_CALL","CALL_NOW","CALL_ME","APPLY_NOW","BUY","GET_QUOTE","SUBSCRIBE","RECORD_NOW","VOTE_NOW","GIVE_FREE_RIDES","REGISTER_NOW","OPEN_MESSENGER_EXT","EVENT_RSVP","CIVIC_ACTION","SEND_INVITES","REFER_FRIENDS","REQUEST_TIME","SEE_MENU","SEARCH","TRY_IT","TRY_ON","LINK_CARD","DIAL_CODE","FIND_YOUR_GROUPS","START_ORDER"]}}}},"adSetId":{"type":"string","description":"When present, switches to the attach shape: adds one new ad to this existing ad set without creating a new campaign. Mutually exclusive with `creatives[]`.\n\n**Inherited from the ad set on Meta:** budget, targeting, goal, schedule and bid strategy. Passing `bidStrategy` in attach mode returns 400 (change an ad set's bid with `PUT /v1/ads/ad-sets/{adSetId}`). `dynamicCreative` returns 400 in attach mode: omit `adSetId` to create a new dynamic ad set instead.\n\n**Creative.** The attached ad takes the full single-creative surface: `headline`/`body`/`description`/`callToAction` plus one of:\n\n- `imageUrl`/`video`\n- `placementAssets` (its own per-placement Feed/Story assets)\n- `translations`/`defaultLocale` (its own per-locale asset feed, Meta only)\n\nPass `leadGenFormId` on EVERY ad attached to a lead ad set: the parent must be ON_AD (true for ad sets created via goal `lead_generation`), and Meta rejects a formless ad there.\n\nTo build N full ads sharing one ad set, create the first ad via the normal shape, then attach the rest one call each.\n\n**Platforms.** Supported on Meta (facebook, instagram), Google Ads, TikTok, LinkedIn and Reddit Ads.\n\n- TikTok: `adSetId` is the ad group ID; the new ad inherits the ad group's bid, budget and targeting.\n- LinkedIn: `adSetId` is the LinkedIn Campaign ID (numeric). We attach a new Creative to that Campaign, so its `platformSpecificData` bidding, targeting, budget and schedule are inherited (passing those fields returns 400).\n- Reddit Ads: `adSetId` is the AD GROUP id. Only the post and the ad are created; the ad group keeps its budget, schedule, targeting, bid and optimization. `goal` is not required. An ad group of another ad account returns 404.\n- Reddit Ads, rejected with 400: `budgetAmount`, `budgetType`, `startDate`, `endDate`, targeting fields, `promotedObject`, `tracking.pixelId` and `optimizationGoal`.\n\n**Google Ads.** `adSetId` is the AD GROUP id (numeric). `goal` is not required: the ad group keeps its campaign's bidding, budget and targeting. `validateOnly` is supported.\n\n- `campaignType` is read from the ad group's campaign (Search, Display or Demand Gen) and can be omitted. A contradicting `campaignType` returns 400, an ad group Google does not know in that customer returns 404, and any other campaign type returns 422.\n- A Search ad needs `headline` + `body` + `linkUrl`; a Display ad also needs `images.landscape` + `images.square` + `businessName`.\n- Google allows 3 responsive search ads per ad group: a fourth returns 422 naming the limit (`RESPONSIVE_SEARCH_ADS_PER_AD_GROUP`) and the ad group.\n- `budgetAmount`/`budgetType` and bidding fields (`bidStrategy`, `bidAmount`, `portfolioBidStrategyId`) return 400; the ad group already owns them.\n- With `campaignType: \"demand_gen\"` the ad group must belong to a Demand Gen campaign (otherwise 400). `demandGen` carries only the ad's creative, and the new ad is created PAUSED.\n- Demand Gen ad group settings return 400: geo, languages, `demandGen.channels`/`audience`/`audienceId`/ `adGroupName`.\n"},"existingCampaignId":{"type":"string","description":"Create the new objects under this EXISTING campaign instead of creating a new one. Supported on Meta, Google Ads, LinkedIn, TikTok and Reddit Ads. Mutually exclusive with `adSetId`.\n\n- TikTok: creates the ad group and the ad under this campaign. The campaign is neither created nor activated, and its objective must fit `goal`. Not with `smartPlus`.\n- Meta: adds the new ad set under this campaign (multi-ad-set audience testing). Its budget matches the campaign's mode: for a CBO campaign (campaign-level budget) omit `budgetAmount`/`budgetType`, since the campaign owns the budget; for an ABO campaign pass them (they go on the new ad set).\n- Meta with `creatives[]`: the new ad set gets one ad per entry.\n- LinkedIn: creates a new Campaign (and its Creative) under this EXISTING CampaignGroup.\n- Google Ads: creates a new ad group under this campaign. It inherits the campaign's budget, so omit `budgetAmount`/`budgetType` (and any bidding field), or the request returns 400.\n- Google Ads with `campaignType: \"demand_gen\"`: the campaign must be Demand Gen (otherwise 400). The new ad group (with its geo, languages, channels and audience from the request) and its ad are created in one atomic request, the ad group PAUSED. Schedule and `locationTargetingType` belong to the campaign and return 400.\n- Google Ads, campaign migrated from Discovery that still targets locations and languages on the campaign: geo and language fields return 400 on a new ad group, which follows the campaign's targeting.\n- Google Ads failure: only the entities we authored are cleaned up. The pre-existing parent is left untouched and is never (re)activated.\n- Reddit Ads: creates a new ad group and the ad under this campaign. `goal` may be omitted (the campaign's objective decides it); any other goal returns 400 naming the one to send. If the ad fails, the new ad group is archived.\n- Reddit Ads dates: the ad group must start no earlier than a future campaign start and end no later than the campaign end (400 otherwise). Without `endDate` it ends with the campaign.\n- Reddit Ads, campaign without a campaign budget: send `budgetAmount`/`budgetType` for the new ad group (400 without them). Bid, conversion event and pixel work as on a new campaign.\n- Reddit Ads under campaign budget optimization: the ad group takes the campaign's bid, goal type, optimization event and pixel and has no budget of its own. `budgetAmount`/`budgetType`, bid fields, or another conversion event or pixel return 400, as does an `endDate` when the campaign has no end date.\n- Reddit Ads errors: a campaign of another ad account returns 404, a Reddit Max campaign 422.\n"},"phoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"Meta attach shape only (`adSetId`). The phone number (E.164, e.g. `+4712345678`) for an ad added to a \"website and phone call\" ad set (destination_type `WEBSITE_AND_PHONE_CALL`), sent as the creative's call configuration.\n\nOptional: when omitted, the number on the ad set's existing ads is reused; if none carries one, the request is a 400.\n\nRejected with 400 on any other ad set, with `existingCreativeId`, without `adSetId`, or on other platforms (a new call campaign is `POST /v1/ads/call`).\n"},"existingCreativeId":{"type":"string","description":"Meta only. Reuse an EXISTING ad creative by id instead of building a new one from the copy/media fields (which are then ignored).\n\n- Combine with `existingCampaignId` to build a multi-ad-set campaign that shares one creative.\n- Mutually exclusive with `creatives[]`, `dynamicCreative`, and `placementAssets`.\n- The creative id used is returned as `creativeId` on the create response.\n"},"businessName":{"type":"string","maxLength":25,"description":"Google Display only"},"boardId":{"type":"string","description":"Pinterest only. Board ID (auto-creates if not provided)."},"organizationId":{"type":"string","description":"LinkedIn only (ignored by every other platform). The Company Page that authors the Direct Sponsored Content (\"dark\") post backing the ad. Accepts a numeric organization ID or a full `urn:li:organization:N` URN.\n\nRequired unless it defaults:\n\n- to the page, when the resolved `accountId` is a connected LinkedIn Company-Page account;\n- to the owning organization, when the LinkedIn ad account is org-owned.\n\nThe authenticated member must be an ADMINISTRATOR or DIRECT_SPONSORED_CONTENT_POSTER of this page, and the page must be associated with the ad account, or LinkedIn returns 403."},"targeting":{"description":"Nested targeting object: the same TargetingSpec shape as `POST /v1/ads/boost`, `POST /v1/ads/targeting/reach-estimate`, and `saved_targeting` audiences.\n\nMerged UNDER the flat inline targeting fields below: `savedTargetingId` < `targeting` < flat fields (a flat field present on the body replaces the nested value entirely). Both forms are equivalent; use whichever your integration already builds.\n\nReddit-only targeting (`communities`, `excludedCommunities`, `conversationKeywords`, `excludedConversationKeywords`) is sent here.\n","allOf":[{"$ref":"#/components/schemas/TargetingSpec"}]},"countries":{"type":"array","items":{"type":"string"},"description":"ISO 3166-1 alpha-2 country codes (e.g. ['NL']). Defaults to ['US'] when no other geo targeting (flat or nested `targeting`) is provided. (LinkedIn and OpenAI Ads currently honour country-level targeting only; any other targeting field returns 400 for OpenAI Ads.)"},"countryGroups":{"type":"array","description":"Meta only. Continents and trade blocs (`geo_locations.country_groups`),\nfor targeting a whole region without listing its countries. Combines with\n`countries` rather than replacing it. Discoverable via\n`GET /v1/ads/targeting/search?dimension=geo&geoType=country_group`.\n","items":{"type":"string","enum":["africa","asia","europe","north_america","south_america","oceania","central_america","caribbean","eea","euro_area","nafta","mercosur","afta","apec","gcc","cisfta","emerging_markets","itunes_app_store","android_free_store","android_paid_store"]}},"cities":{"type":"array","description":"City-level geo targeting (Meta, Google and TikTok). An entry is `{ key }` or the key alone as a plain string (`[\"1006410\"]`).\n\nEach city is targeted by the platform's opaque `key` (the city ID), found via `GET /v1/ads/targeting/search?dimension=geo&q=<name>&countryCode=<ISO>`.\n\n**Radius (Meta only):** optional `radius` + `distance_unit` extend targeting beyond city limits (e.g. radius 25 km around the center). Set both or omit both (Meta defaults to ~16 km).\n\n- **Meta:** cannot overlap with the same country in `countries` (Meta returns a \"locations overlap\" error). Drop the country or scope it to a different one.\n- **TikTok:** keys are numeric location ids and can be sent without `countries`.\n","items":{"oneOf":[{"type":"string","description":"The city id alone, e.g. \"1006410\" (same as { key: \"1006410\" })."},{"type":"object","required":["key"],"properties":{"key":{"type":"string","description":"City id from /v1/ads/targeting/search results (Meta city key, Google geo target constant id, TikTok location id)."},"radius":{"type":"number","description":"Optional radius around the city. Must be set together with distance_unit. 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)."},"distance_unit":{"type":"string","enum":["mile","kilometer"],"description":"Unit for radius. Required if radius is set."}}}]}},"regions":{"type":"array","description":"Region-level (state/province) geo targeting (Meta, Google and TikTok). Each region is targeted by the platform's opaque `key` (the region ID) which can be looked up via `GET /v1/ads/targeting/search?dimension=geo&q=<name>&countryCode=<ISO>`. An entry may also be the key alone as a plain string.\n","items":{"oneOf":[{"type":"string"},{"type":"object","required":["key"],"properties":{"key":{"type":"string","description":"Platform region ID, from /v1/ads/targeting/search results."}}}]}},"ageMin":{"type":"integer","minimum":13,"maximum":65},"ageMax":{"type":"integer","minimum":13,"maximum":65},"interests":{"type":"array","description":"Interest objects from /v1/ads/targeting/search?dimension=interest (or dimension=interestKeyword on TikTok). Each must include id and name.\n\n**TikTok:**\n\n- Bare numeric ids are interest categories (`interest_category_ids`).\n- Ids like `keyword:123456` from `dimension=interestKeyword` are additional interests (`interest_keyword_ids`).\n- Any other id returns 422 naming `targeting.interests`.\n- TikTok matches people who fit ANY selected interest, additional interest or behavior (one OR'd group). That group is ANDed with location, age, gender and the other dimensions.\n","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"zips":{"type":"array","description":"Postal/ZIP geo targeting. `key` is the platform's postal location ID from /v1/ads/targeting/search?dimension=geo&geoType=zip. Supported on Meta, Google, TikTok, Pinterest, X.","items":{"oneOf":[{"type":"string"},{"type":"object","required":["key"],"properties":{"key":{"type":"string"},"name":{"type":"string"}}}]}},"metros":{"type":"array","description":"DMA / metro-area geo targeting (Meta and TikTok). `key` is the platform's metro ID from /v1/ads/targeting/search?dimension=geo&geoType=metro (TikTok metros appear as type `metro`, e.g. the New York DMA).","items":{"oneOf":[{"type":"string"},{"type":"object","required":["key"],"properties":{"key":{"type":"string"},"name":{"type":"string"}}}]}},"customLocations":{"type":"array","description":"Point-radius (lat/lng) geo targeting. Meta only (custom_locations). Rejected on platforms without radius support.","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"},"distanceUnit":{"type":"string","enum":["mile","kilometer"]},"name":{"type":"string"},"address":{"type":"string"}}}},"behaviors":{"type":"array","description":"Behaviour entities from /v1/ads/targeting/search?dimension=behavior (Meta, TikTok and LinkedIn). Each must include id.\n\n**On TikTok:**\n\n- Targets people who interacted with videos (watched to the end, liked, commented or shared, last 15 days) or creators (followed or viewed the profile) in the picked categories.\n- Or people who viewed videos with a picked hashtag: `hashtag:<id>` ids from `dimension=hashtag`, sent as a `HASHTAG_RELATED` action with `VIEW_HASHTAG`.\n- The ad group uses the TikTok placement only.\n- Behaviors are OR'd with interests and additional interests.\n","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"workPositions":{"type":"array","description":"Meta only. Job title entities from /v1/ads/targeting/search?dimension=workPosition. Each must include id. Rejected on other platforms (use LinkedIn's `jobTitles` there).","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"workEmployers":{"type":"array","description":"Meta only. Employer entities from /v1/ads/targeting/search?dimension=workEmployer. Each must include id.","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"workIndustries":{"type":"array","description":"Meta only. Work-industry entities from /v1/ads/targeting/search?dimension=workIndustry. Each must include id. Rejected on other platforms (use LinkedIn's `industries` there).","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"incomeTier":{"type":"string","enum":["top_5","top_10","top_10_25","top_25_50"],"description":"Normalized household-income tier. Meta and TikTok express all four; Google maps only\n`top_10`; rejected on LinkedIn, X, and Pinterest. On Meta, income targeting is incompatible\nwith housing/employment/credit `specialAdCategories`.\n"},"languages":{"type":"array","items":{"type":"string"},"description":"Language codes, e.g. [\"en\",\"es\"].\n\n- Google: campaign language targeting (language_constant) using Google's language codes (ISO 639-1, plus variants such as `zh_CN`). Unknown codes return 400.\n- Meta: a bare code targets all regional variants (\"en\" = all English); use a region-qualified code for a specific one (\"en_GB\", \"pt_BR\", \"zh_TW\"). Meta numeric locale ids (e.g. \"24\" for English UK) are also accepted. Unknown values are rejected. POST /v1/ads/boost takes the same format in `targeting.languages`.\n- Other ad platforms use their own language-code systems."},"placements":{"type":"object","description":"Meta only; non-Meta platforms reject this field. Manual ad placements. Omit for automatic placements (Meta's default, recommended for most cases, since Meta optimises delivery across all eligible surfaces).\n\nWhen 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}`.\n\nEnum membership is validated here. Meta additionally enforces co-selection rules (e.g. some positions require their parent publisher platform) and returns an actionable error, which we surface.\n","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","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."}}},"savedTargetingId":{"type":"string","description":"ID of a `saved_targeting` audience (created via POST /v1/ads/audiences). When set, its stored\nTargetingSpec is expanded as the base targeting; inline fields on this body merge on top. Lets you\nreuse a named targeting preset without re-sending every field.\n"},"rawTargeting":{"type":"object","additionalProperties":true,"description":"Meta only. A raw Meta-native targeting spec (snake_case: `geo_locations`, `age_min`, `excluded_custom_audiences`, `flexible_spec`, `targeting_automation`, `user_os`, `wireless_carrier`, business places, etc.), the exact shape `GET /v1/ads/{adId}` returns for external ads.\n\nSent alone, it reaches the ad set VERBATIM (the path for cloning a campaign's targeting exactly). Meta validates it and surfaces any errors.\n\n**Combining with camelCase fields** (countries/regions/cities/interests/ageMin/..., `targeting`, `savedTargetingId`, `audienceId`): rawTargeting is the BASE layer and the built camelCase spec is merged on top, key by key, with camelCase winning on collision.\n\nThe camelCase precedence chain stays `savedTargetingId` < `targeting` < flat fields. Merge rules:\n\n- Inside `geo_locations` and `excluded_geo_locations` the merge goes one level deep: built sub-keys win, and raw-only sub-keys such as `location_types` survive alongside built `countries`.\n- Array values (`flexible_spec`, ...) are replaced as a WHOLE key when the camelCase spec builds them, never element-merged.\n- With rawTargeting present, the defaults the camelCase builder normally injects (US geo, `targeting_automation.advantage_audience: 0`) are suppressed, so raw values are not clobbered.\n\nInclude `targeting_automation` in the raw spec (or send `advantageAudience`), as Meta requires it on create. When cloning an EU campaign, also pass `dsaBeneficiary` / `dsaPayor` (separate fields, not part of targeting).\n"},"specialAdCategories":{"type":"array","description":"Declares the ad's special category, required for housing, employment, credit, or\npolitical/social-issue ads.\n\n- Meta: every value. Setting a housing, employment or credit category disables income/zip\n  targeting on Meta.\n- TikTok: HOUSING, EMPLOYMENT and CREDIT, sent as the new campaign's `special_industries`\n  (TikTok requires one for these ads aimed at the US or Canada). Other values return 400.\n- TikTok targeting: the create (and `validateOnly`) returns 400 naming the field for ZIP codes\n  (`targeting.zips`), gender, ages under 18 (`targeting.ageMin`), interest keywords (`keyword:`\n  ids in `targeting.interests`) and hashtag behaviors.\n- TikTok also refuses Smart Targeting (`smartTargeting`) and lookalike audiences\n  (`targeting.audienceInclude` / `targeting.audienceExclude`). Without an age, the ad group\n  targets 18+.\n- TikTok sets the category when the campaign is created, so it is a 400 with `smartPlus`,\n  `existingCampaignId` or `adSetId`.\n","items":{"type":"string","enum":["HOUSING","EMPLOYMENT","CREDIT","FINANCIAL_PRODUCTS_SERVICES","ISSUES_ELECTIONS_POLITICS","ONLINE_GAMBLING_AND_GAMING"]}},"specialAdCategoryCountry":{"type":"array","description":"Meta (metaads) only. 2-letter ISO country codes the special ad category applies to. Requires\nspecialAdCategories to be set (400 otherwise). Ignored when joining an existing campaign via\nexistingCampaignId (the existing campaign's category/country already governs it).\n","items":{"type":"string"}},"regionalRegulatedCategories":{"type":"array","description":"Meta only. Regional regulation categories required when the ad set targets certain countries.\nKnown values: AUSTRALIA_FINSERV, AUSTRALIA_UNIVERSAL, BRAZIL_REGULATION, INDIA_FINSERV,\nMALAYSIA_UNIVERSAL, SINGAPORE_UNIVERSAL, TAIWAN_FINSERV, TAIWAN_UNIVERSAL, THAILAND_UNIVERSAL. Meta rejects the ad set without this when\nthe targeting geo includes the corresponding country.\n","items":{"type":"string"}},"regionalRegulationIdentities":{"type":"object","additionalProperties":{"type":["string","integer"]},"description":"Meta only. Verified identity IDs of the beneficiary and payer for each declared regionalRegulatedCategories value. Ignored when adSetId adds the ad to an existing ad set.\n\nMeta may require them on ad sets created through the API even when a default beneficiary and payer are set in Ads Manager advertising settings (seen on AUSTRALIA_FINSERV), so sending them explicitly is the reliable path.\n\n**Value**: the Verified identity ID (Meta Business Settings > Verified identities), not a Page or Business ID. Beneficiary and payer may be the same ID. The IDs reach Meta unchanged.\n\nSend each ID as a string of digits: Verified identity IDs can have 17 digits, more than a JSON number holds exactly, and a number that arrives rounded is rejected. Numbers up to 9007199254740991 are still accepted.\n\n**Keys by category**:\n\n- AUSTRALIA_FINSERV: australia_finserv_beneficiary / australia_finserv_payer\n- TAIWAN_FINSERV: taiwan_finserv_beneficiary / taiwan_finserv_payer\n- INDIA_FINSERV: india_finserv_beneficiary / india_finserv_payer\n- TAIWAN_UNIVERSAL: taiwan_universal_beneficiary / taiwan_universal_payer\n- SINGAPORE_UNIVERSAL: singapore_universal_beneficiary / singapore_universal_payer\n- AUSTRALIA_UNIVERSAL, BRAZIL_REGULATION, MALAYSIA_UNIVERSAL and THAILAND_UNIVERSAL: universal_beneficiary / universal_payer\n\n**Errors**: when Meta rejects the ad set for a missing verified advertiser, the error carries param regionalRegulationIdentities, details.expectedIdentityKeys (the keys the declared categories expect), details.suggestedCategories (the markets Meta ties to that subcode) and Meta's metaCode, metaSubcode and fbtraceId.\n"},"endDate":{"type":"string","format":"date-time","description":"When the ad ends. If omitted: on a lifetime budget, the ad ends 7 days after it starts (reported in `appliedDefaults.endDate`); a daily budget runs until paused.\n\nRead like `startDate`: account timezone on Meta, TikTok, X, Pinterest, OpenAI and Reddit; whole account-local days on Google; UTC on LinkedIn. A date-only end runs to 23:59:59 local.\n\nOn a Pinterest ad account that needs Campaign Budget Optimization, the end also goes on the campaign, daily budget included.\n\n400 when it is not an ISO 8601 date or date-time, or when the ad joins a parent that keeps its own dates: `adSetId` on Meta, TikTok, Google, LinkedIn and Reddit, and `existingCampaignId` on Google."},"startDate":{"type":"string","format":"date-time","description":"Ad-set start time (ISO 8601, e.g. \"2026-06-10T09:00:00Z\"). When omitted the ad starts delivering immediately. Same field as on `POST /v1/ads/boost`.\n\nMaps to the ad set's start: Meta `start_time`, TikTok ad group `schedule_start_time`, LinkedIn / Pinterest / X / Google campaign start. For lifetime budgets Meta also requires `endDate`.\n\n**Values without an offset** (`YYYY-MM-DD`, `YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DDTHH:MM:SS`):\n\n- Meta, TikTok, X, Pinterest, OpenAI and Reddit: read in the ad account timezone (Meta itself would read it as UTC).\n- Google: runs whole days in the customer account timezone and takes the value's calendar date as written.\n- LinkedIn: ad accounts carry no timezone, so it is read as UTC.\n\nThe created ad's `schedule` echoes the start and end the platform stored, as UTC instants. When attaching to an existing ad set (`adSetId`) it is that ad set's start and end.\n"},"pageId":{"type":"string","description":"Meta only. The Facebook Page the ad runs as (`object_story_spec.page_id`). Defaults to the Page bound to the connection.\n\nPass another Page ID to run the ad as that Page. Any Page granted to the connection is accepted (for a business-login connection, every Page granted in Meta's dialog; list them with GET /v1/ads/instagram-accounts).\n\n- The Instagram identity is re-resolved for that Page unless `instagramAccountId` is set.\n- A Page the connection cannot see is a 400 on `pageId` naming the granted Pages.\n"},"instagramAccountId":{"type":"string","description":"Meta only. Overrides the Instagram account the ad is delivered as. Pass an Instagram Business Account ID (e.g. 17841...), mapped to the creative's `instagram_user_id`; it is sent as-is and never replaced. Useful when a Page has more than one eligible IG account.\n\nWhen omitted, we use the Instagram account linked to the Page. Formats that need an Instagram actor without one use the actor the Page's other ads already run as, then the Page's page-backed Instagram account.\n\nIf Meta refuses that default because the ad account has no access to it (200/1815199), the creative is retried once with an Instagram account the ad account is authorized for. With none, the request fails with a 422 on `instagramAccountId` (list the usable accounts with GET /v1/ads/instagram-accounts).\n\nA creative replaced later through /v1/ads/{adId} follows the same rule.\n"},"dynamicCreative":{"type":"object","description":"Meta only. Dynamic Creative: supply a POOL of assets and Meta auto-combines and optimises them into the best-performing variations within a single ad (mapped to the creative's `asset_feed_spec`).\n\n- The top-level single-creative fields (`imageUrl`, `headline`, `body`, `linkUrl`, `callToAction`) are ignored when this is set.\n- Mutually exclusive with the `creatives[]` multi-creative shape.\n- Exactly ONE of `imageUrls` / `videoUrls` is required (Meta allows one ad format per asset feed; sending both → 400).\n- Limits remain 10 images or videos and 5 bodies, titles or descriptions.\n- Multiple headlines go in `titles`; multiple primary texts go in `bodies`.\n- The ad set is created with `is_dynamic_creative: true`. Combining this field with `adSetId` returns 400: omit `adSetId` to create a new dynamic ad set.\n","properties":{"imageUrls":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","format":"uri"},"description":"Pool of image URLs (1-10). Uploaded to the ad account and referenced by hash in the asset feed. Mutually exclusive with `videoUrls`."},"videoUrls":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","format":"uri"},"description":"Pool of video URLs (1-10). Uploaded to the ad account and referenced by video id in the asset feed. No thumbnails are needed: Meta auto-generates a poster per video. Mutually exclusive with `imageUrls`; `adFormat` defaults to SINGLE_VIDEO."},"bodies":{"type":"array","maxItems":5,"items":{"type":"string"},"description":"Primary-text variations (the body copy)."},"titles":{"type":"array","maxItems":5,"items":{"type":"string"},"description":"Headline variations."},"descriptions":{"type":"array","maxItems":5,"items":{"type":"string"},"description":"Description (link caption) variations."},"linkUrls":{"type":"array","items":{"type":"string","format":"uri"},"description":"Destination URL variations. At least one is required unless `goal` is `lead_generation`."},"callToActionTypes":{"type":"array","items":{"type":"string","enum":["BOOK_TRAVEL","CONTACT_US","DONATE","DONATE_NOW","DOWNLOAD","GET_DIRECTIONS","GO_LIVE","INTERESTED","LEARN_MORE","SEE_DETAILS","LIKE_PAGE","MESSAGE_PAGE","RAISE_MONEY","SAVE","SEND_TIP","SHOP_NOW","SIGN_UP","VIEW_INSTAGRAM_PROFILE","INSTAGRAM_MESSAGE","LOYALTY_LEARN_MORE","PURCHASE_GIFT_CARDS","PAY_TO_ACCESS","SEE_MORE","TRY_IN_CAMERA","WHATSAPP_LINK","GET_IN_TOUCH","TRY_NOW","ASK_A_QUESTION","START_A_CHAT","CHAT_NOW","ASK_US","CHAT_WITH_US","SHOP_ON_RETAILER","BOOK_NOW","CHECK_AVAILABILITY","ORDER_NOW","WHATSAPP_MESSAGE","GET_MOBILE_APP","INSTALL_MOBILE_APP","USE_MOBILE_APP","INSTALL_APP","USE_APP","PLAY_GAME","TRY_DEMO","WATCH_VIDEO","WATCH_MORE","OPEN_LINK","NO_BUTTON","LISTEN_MUSIC","MOBILE_DOWNLOAD","GET_OFFER","GET_OFFER_VIEW","BUY_NOW","BUY_TICKETS","UPDATE_APP","BET_NOW","ADD_TO_CART","SELL_NOW","GET_SHOWTIMES","LISTEN_NOW","GET_EVENT_TICKETS","REMIND_ME","SEARCH_MORE","PRE_REGISTER","SWIPE_UP_PRODUCT","SWIPE_UP_SHOP","PLAY_GAME_ON_FACEBOOK","VISIT_WORLD","OPEN_INSTANT_APP","JOIN_GROUP","GET_PROMOTIONS","SEND_UPDATES","INQUIRE_NOW","VISIT_PROFILE","CHAT_ON_WHATSAPP","EXPLORE_MORE","CONFIRM","JOIN_CHANNEL","MAKE_AN_APPOINTMENT","ASK_ABOUT_SERVICES","BOOK_A_CONSULTATION","GET_A_QUOTE","BUY_VIA_MESSAGE","ASK_FOR_MORE_INFO","VIEW_PRODUCT","VIEW_CHANNEL","WATCH_LIVE_VIDEO","JOIN_LIVE_VIDEO","IMAGINE","WATCH_NOW","STREAM_NOW","BUY_ACTIVITY_TICKETS","CALL","MISSED_CALL","CALL_NOW","CALL_ME","APPLY_NOW","BUY","GET_QUOTE","SUBSCRIBE","RECORD_NOW","VOTE_NOW","GIVE_FREE_RIDES","REGISTER_NOW","OPEN_MESSENGER_EXT","EVENT_RSVP","CIVIC_ACTION","SEND_INVITES","REFER_FRIENDS","REQUEST_TIME","SEE_MENU","SEARCH","TRY_IT","TRY_ON","LINK_CARD","DIAL_CODE","FIND_YOUR_GROUPS","START_ORDER"]},"description":"CTA-button variations. Required."},"adFormat":{"type":"string","enum":["SINGLE_IMAGE","CAROUSEL_IMAGE","SINGLE_VIDEO"],"description":"Asset-feed ad format. Must match the pool: SINGLE_IMAGE / CAROUSEL_IMAGE require `imageUrls`, SINGLE_VIDEO requires `videoUrls` (400 otherwise). Defaults to SINGLE_IMAGE with `imageUrls`, SINGLE_VIDEO with `videoUrls`."}}},"carouselCards":{"type":"array","minItems":2,"maxItems":10,"description":"Carousel cards. Behavior per platform:\n\n**Reddit:** builds a carousel ad. Each card has its image, destination (card `linkUrl`, falling back to top-level `linkUrl`; 400 when neither is set), call to action (card `callToAction`, falling back to the top-level one) and caption (card `headline`, else `description`). `headline` is still required.\n\n**Meta only:** a hand-built carousel of 2-10 authored cards, sent in order as the creative's `link_data.child_attachments`. Unlike `dynamicCreative`, you author every card's copy and link.\n\n- Meta may still reorder cards for performance (`multi_share_optimized` defaults to true); send `optimizeCardOrder: false` to keep your order.\n- Requires top-level `body` and `callToAction`; `linkUrl` too UNLESS `leadGenFormId` is set. These become the ad's Destination and button (`link_data.link` / `link_data.call_to_action`) and the per-card fallback.\n- Mutually exclusive with `imageUrl`/`video`, `creatives[]`, `dynamicCreative`, `placementAssets`, `existingCreativeId`, `adSetId` and goal `catalog_sales`.\n- With `leadGenFormId` it builds a carousel Instant-Form lead ad: `linkUrl` and per-card `linkUrl` become OPTIONAL, forwarded as real destinations when sent; when omitted, the destination falls back to Meta's lead-form link.\n","items":{"type":"object","required":["imageUrl"],"properties":{"imageUrl":{"type":"string","format":"uri","description":"Card image; uploaded to the ad account and referenced by hash."},"linkUrl":{"type":"string","format":"uri","description":"Card destination URL. Defaults to the top-level linkUrl, or Meta's lead-form link when leadGenFormId is set and neither is provided."},"headline":{"type":"string","maxLength":255,"description":"Card headline, shown below the card image."},"description":{"type":"string","maxLength":255,"description":"Card description, shown under the headline."},"callToAction":{"type":"string","description":"Card CTA override. Defaults to the top-level callToAction; same enum."}}}},"optimizeCardOrder":{"type":"boolean","description":"Meta only (a 400 on any other platform), and only with `carouselCards` (a 400 without them). Sets the creative's `link_data.multi_share_optimized`.\n\n- `false`: keeps the cards in the order given. Meta then takes at most 5 cards, so `false` with more than 5 `carouselCards` is a 400.\n- `true`: Meta picks and reorders the cards for performance (up to 10).\n- Omitted: nothing is sent and Meta's default (`true`) applies.\n"},"defaultLocale":{"type":"string","description":"Meta only. Language the top-level copy is written in (e.g. `en`, `pt_BR`), used by the `translations` default rule. Defaults to `en`. Meta rejects a language asset feed whose default rule carries no locales of its own. Must NOT also appear as an entry in `translations`."},"translations":{"type":"array","minItems":1,"maxItems":10,"description":"Meta only. Multi-language ads (Dynamic Language Optimization, the \"Languages\" toggle in Ads Manager): ONE ad with per-locale copy and, optionally, per-locale media. Social proof (likes/comments/shares) stays on a SINGLE post instead of splitting across one ad per language.\n\nThe ad's top-level copy is the DEFAULT for every locale you do NOT list, and counts as one of the language variants.\n\n**Text does NOT inherit** (the opposite of what you might expect). Every entry needs its own `headline`, `body` AND `description`, all DISTINCT from each other and from the top-level copy. `description` is therefore effectively required on the ad whenever `translations` is present, though optional otherwise.\n\nWhy: Meta deduplicates identical strings in the asset feed, so two locales sharing a string collapse into one asset.\n\nThe create then fails with a misleading \"Too few ... texts provided in asset creation\" (subcode 1885817) naming a field that is present. We validate first and return a 400 naming the locale and field.\n\nDo NOT list `defaultLocale` inside `translations`: Meta rejects the duplicate with \"The language asset feed includes an unsupported targeting field\" (subcode 1885985).\n\n**Media DOES inherit** and is uploaded once when shared. `linkUrl` inherits too: each locale may name its own landing page, and unlisted locales fall back to the top-level `linkUrl`.\n\nMeta enforces Dynamic Creative image dimensions on language feeds, so an `imageUrl` that works on a normal ad may fail with \"The following images have invalid dimensions for Dynamic Creative\" (subcode 1885558). Video is not affected.\n\nMutually exclusive with `dynamicCreative`, `placementAssets`, `carouselCards`, `existingCreativeId` and `creatives[]`: Meta allows one `asset_feed_spec` shape per creative.\n","items":{"type":"object","required":["locale","headline","body","description"],"properties":{"locale":{"type":"string","description":"Language code, resolved to Meta's numeric locale id. Bare codes target the '(All)' umbrella (`es` = every Spanish variant); region-qualified codes target the variant (`pt_BR`, `en_GB`)."},"headline":{"type":"string","maxLength":255,"description":"Headline for this language. REQUIRED, and must differ from every other locale and from the ad's top-level headline."},"body":{"type":"string","description":"Primary text for this language. REQUIRED, and must differ from every other locale and from the ad's top-level body."},"description":{"type":"string","maxLength":255,"description":"Link description for this language. REQUIRED, and must differ from every other locale and from the ad's top-level description."},"linkUrl":{"type":"string","format":"uri","description":"Destination URL for this language. Inherits the ad's top-level `linkUrl` when omitted, and requires it to be present (400 otherwise): the top-level URL is the destination for every locale you did not override. Unlike text, identical URLs across locales are fine (they share one asset)."},"imageUrl":{"type":"string","format":"uri","description":"Image for this language. Inherits the ad's `imageUrl` when omitted. The feed is all-image OR all-video."},"videoUrl":{"type":"string","format":"uri","description":"Video for this language. Inherits the ad's `video.url` when omitted. The feed is all-image OR all-video."},"thumbnailUrl":{"type":"string","format":"uri","description":"Poster frame for this language's video."}}}},"placementAssets":{"allOf":[{"$ref":"#/components/schemas/MetaPlacementAssets"}],"description":"Meta only. Pins a SPECIFIC asset (image OR video) to each placement group on a SINGLE ad (e.g. a 9:16 on Stories/Reels and a 4:5 on Feed). The same thing Ads Manager produces with \"different creative per placement\", mapped to the creative's `asset_feed_spec` + `asset_customization_rules`.\n\nDeterministic pinning, NOT the auto-optimizing pool of `dynamicCreative` (mutually exclusive). Cannot be combined with `creatives[]` or top-level `bodies`/`headlines`/`descriptions` arrays.\n\nWorks on the legacy single shape AND the attach shape: `adSetId` + placementAssets adds one placement-customized ad to an existing ad set. To build N per-placement ads sharing one ad set, create the first normally and attach the rest.\n\n**Text.** Each rule can override `headline`, `body` and `description` with one string per field. Omitted fields and unmatched placements use the top-level copy; `linkUrl` and `callToAction` remain shared. Zernio emits labelled text with `optimization_type: PLACEMENT`. Multiple text options rotating within a placement are not supported by this input.\n\n**Placements.** Each rule's `placements` accepts the same fields as the top-level `placements` object; Meta enforces co-selection rules and returns an actionable error.\n\nMeta controls text rendering by placement and format. Validation accepts these fields but does not prove that every field appears in delivery. Preview the ad, and put copy that must always be visible into the image or video itself.\n\n`validateOnly: true` supports all-image placementAssets, and video placementAssets with a video id in every slot and no thumbnails, without uploading or creating anything. Video URLs and thumbnails need an upload, so they return 400.\n\n**Media.** A block is all-image OR all-video, never mixed (Meta's asset_feed_spec carries one ad format). Exactly one catch-all default is required.\n\n- Image mode: `defaultImageUrl` + `rules[].imageUrl`.\n- Video mode: `defaultVideoUrl` or `defaultVideoId` + `rules[].videoUrl` or `rules[].videoId`, with optional `thumbnailUrl`/`defaultThumbnailUrl` posters (Meta auto-generates them when omitted). An id reuses a video already on the ad account and wins over a URL in the same slot; the two can mix across slots.\n"},"audienceId":{"type":"string","description":"Custom audience ID for targeting"},"campaignType":{"type":"string","enum":["display","search","pmax","demand_gen"],"description":"Google only. Omitted, it is display on a new campaign, and the existing campaign's own type with `existingCampaignId` or `adSetId` (Search, Display or Demand Gen; other types return 422). Performance Max requires assetGroup and Demand Gen requires demandGen; both are always created PAUSED."},"locationTargetingType":{"allOf":[{"$ref":"#/components/schemas/GoogleLocationTargetingType"}],"description":"Google only (400 elsewhere). Set on the new campaign; a request that joins an existing campaign (`existingCampaignId` or `adSetId`) returns 400, change that campaign with PUT /v1/ads/campaigns/{campaignId}/targeting instead. `presence` reaches only people in or regularly in the targeted locations."},"assetGroup":{"$ref":"#/components/schemas/GooglePmaxAssetGroupInput"},"demandGen":{"$ref":"#/components/schemas/GoogleDemandGenInput"},"keywords":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/KeywordEntry"},"description":"Google Search only. Keywords on the new ad group; entries are strings (BROAD) or { text, matchType }. Editable later via PUT /v1/ads/{adId} targeting.keywords."},"negativeKeywords":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/KeywordEntry"},"description":"Google Search only; other platforms return 400. Ad-group-level negative keywords on the new ad group. Editable later via PUT /v1/ads/{adId} targeting.negativeKeywords."},"campaignNegativeKeywords":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/KeywordEntry"},"description":"Google Search only; other platforms return 400. Campaign-level negative keywords (campaign_criterion.negative), created alongside the ad group. Editable later via PUT /v1/ads/campaigns/{campaignId}/negative-keywords."},"additionalHeadlines":{"type":"array","items":{"oneOf":[{"type":"string","minLength":1,"maxLength":30},{"$ref":"#/components/schemas/GoogleRsaHeadline"}]},"description":"Google Search RSA only. Extra text assets, as strings or objects with text and optional pinnedField. String input remains supported.\n\n- The effective create lists, including primary text and after deduplication, must contain 3-15 headlines and 2-4 descriptions. Excess entries return 400.\n- Each headline is at most 30 characters (Google's limit). A longer one returns 400 naming the field and index (e.g. `additionalHeadlines[2]`); it is never truncated.\n- On Search the same limit applies to `headline` and `longHeadline` (30) and to `body` (90).\n","example":["Schedule Your Posts",{"text":"Build With Zernio","pinnedField":"HEADLINE_2"}]},"additionalDescriptions":{"type":"array","items":{"oneOf":[{"type":"string","minLength":1,"maxLength":90},{"$ref":"#/components/schemas/GoogleRsaDescription"}]},"description":"Google Search RSA only. Extra text assets, as strings or objects with text and optional pinnedField. Existing string input remains supported.\n\n- The effective create lists, including primary text and deduplication, must contain 3-15 headlines and 2-4 descriptions; excess entries return 400.\n- Each description is at most 90 characters (Google's limit). A longer one returns 400 naming the field and index (e.g. `additionalDescriptions[2]`); it is never truncated.\n- On Search the same limit applies to `headline` and `longHeadline` (30) and to `body` (90).\n","example":["Build social publishing into your application.",{"text":"Connect social accounts with one API.","pinnedField":"DESCRIPTION_2"}]},"sitelinks":{"type":"array","minItems":2,"maxItems":20,"description":"Google Search only. Sitelink assets to create and attach at the campaign level. Each entry becomes an Asset (with sitelink_asset + Asset.final_urls) plus a CampaignAsset link (field_type SITELINK).\n\nApproval is async: Google reviews assets after creation; poll asset.policy_summary later to read the verdict.\n\nGoogle requires at least two sitelinks to surface them on an ad; four or more is Google's own recommendation for maximum visibility. The response's creative.sitelinks[] echoes each input plus its Google resourceName.\n","items":{"type":"object","required":["text","linkUrl"],"properties":{"text":{"type":"string","minLength":1,"maxLength":25,"description":"The clickable link text shown under the ad. 25-char cap comes from Google."},"linkUrl":{"type":"string","format":"uri","description":"Final URL the sitelink navigates to."},"description1":{"type":"string","minLength":1,"maxLength":35,"description":"First description line under the link text (optional). 35-char cap."},"description2":{"type":"string","minLength":1,"maxLength":35,"description":"Second description line (optional; usually paired with description1)."}}}},"callouts":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","minLength":1,"maxLength":25},"description":"Google Search only. Short callout texts (max 25 chars each) that appear as\nnon-clickable annotations under the ad, e.g. \"Free shipping\", \"24/7 support\".\nEach becomes one Asset (`callout_asset`) plus a CampaignAsset link with\nfield_type CALLOUT. Response's creative.callouts[] echoes each input plus\nits Google resourceName.\n"},"structuredSnippets":{"type":"array","minItems":1,"maxItems":20,"description":"Google Search only. Structured snippets: one header from Google's\npredefined list plus 3-10 values (max 25 chars each). Each becomes one\nAsset (`structured_snippet_asset`) plus a CampaignAsset link with\nfield_type STRUCTURED_SNIPPET.\n","items":{"type":"object","required":["header","values"],"properties":{"header":{"type":"string","enum":["Amenities","Brands","Courses","Degree programs","Destinations","Featured hotels","Insurance coverage","Models","Neighborhoods","Service catalog","Shows","Styles","Types"],"description":"One of Google's 13 predefined snippet headers."},"values":{"type":"array","minItems":3,"maxItems":10,"items":{"type":"string","minLength":1,"maxLength":25}}}}},"advantageAudience":{"type":"integer","enum":[0,1],"description":"Meta only. Controls the Advantage audience feature (targeting_automation). 0 = disabled (default), 1 = enabled. Meta Marketing API requires this field on all ad set creation requests."},"attributionSpec":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"object","required":["eventType","windowDays"],"properties":{"eventType":{"type":"string","enum":["CLICK_THROUGH","VIEW_THROUGH","ENGAGED_VIDEO_VIEW"]},"windowDays":{"type":"integer","enum":[1,7,28]}}},"description":"Meta only. Conversion attribution window for the ad set, mapping 1:1 to Meta's ad-set `attribution_spec`. Only honored for conversion goals (`conversions`, `lead_generation`, `app_promotion`); ignored for awareness/traffic/engagement. Omit to use Meta's default (`7-day click` + `1-day view`).\n\nMeta enforces the valid combinations (invalid combos surface as a Meta 400):\n\n- `VIEW_THROUGH`: only `windowDays: 1` (7d/28d view windows were removed Jan 2026).\n- `ENGAGED_VIDEO_VIEW`: only `1`, and only alongside `VIEW_THROUGH: 1`.\n- `CLICK_THROUGH: 28`: only on certain objectives.\n\nExample: `[{ \"eventType\": \"CLICK_THROUGH\", \"windowDays\": 7 }, { \"eventType\": \"VIEW_THROUGH\", \"windowDays\": 1 }]`\n"},"gender":{"type":"string","enum":["all","male","female"],"default":"all","description":"Restrict the audience by gender. 'male' targets men only, 'female' targets women only, 'all' (default) targets everyone. Applied on Meta, TikTok, Pinterest and Reddit. Ignored on Google, LinkedIn and X."},"bidStrategy":{"allOf":[{"$ref":"#/components/schemas/BidStrategy"}],"deprecated":true,"description":"Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window. Sending both shapes returns a 400.\n\nBid strategy applied to the ad set (Meta). Per platform:\n\n- **OpenAI Ads:** only this flat field works (`platformSpecificData` is Meta/LinkedIn-only and returns 400 for OpenAI). `LOWEST_COST_WITH_BID_CAP` or `COST_CAP` with `bidAmount` sets a fixed bid (`fixed_bid`, the CPA bid on `conversions`).\n- **OpenAI Ads, automatic:** omitted or `LOWEST_COST_WITHOUT_CAP` uses OpenAI's Maximize Results (`maximize_clicks` for `traffic`, `maximize_conversions` for `conversions`). It needs `budgetType: daily`; a lifetime budget or the `awareness` goal returns 400.\n- **Reddit Ads:** flat field, applied to the new ad group. LOWEST_COST_WITHOUT_CAP or omitted = automatic bidding (BIDLESS). LOWEST_COST_WITH_BID_CAP + `bidAmount` = MANUAL_BIDDING with that bid. COST_CAP + `bidAmount` = MAXIMIZE_VOLUME with that cap. Any other strategy returns 422 before anything is created.\n- **Google:** not deprecated (this flat field is Google's only shape), applied to the campaign this call creates. LOWEST_COST_WITHOUT_CAP = Maximize Conversions. COST_CAP + bidAmount = Target CPA. LOWEST_COST_WITH_MIN_ROAS + roasAverageFloor = Target ROAS.\n- **Google, continued:** LOWEST_COST_WITH_BID_CAP + bidAmount = Maximize Clicks with a CPC ceiling. portfolioBidStrategyId attaches a portfolio strategy instead. Omitted, the campaign falls back to a goal-based default.\n"},"bidAmount":{"type":"number","deprecated":true,"description":"Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400.\n\nBid cap in WHOLE currency units (USD: 5 = $5.00; JPY: 100 = ¥100). Required when `bidStrategy` is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`.\n\nMeta only: `bidAmount` WITHOUT `bidStrategy` requires `existingCampaignId` (400 otherwise). It sets the new ad set's cap under the joined campaign's COST_CAP / LOWEST_COST_WITH_BID_CAP parent; the strategy is inherited from the campaign. Restating bidStrategy here is accepted but has no effect on the ad set.\n\nRejected with 400 in `adSetId` attach mode, which inherits its cap from the platform. Use `PUT /v1/ads/ad-sets/{adSetId}` there instead.\n"},"roasAverageFloor":{"type":"number","deprecated":true,"description":"Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window. Sending both shapes returns a 400.\n\nMinimum ROAS as a decimal multiplier (e.g. 2.0 = 2.0x ROAS). Required when `bidStrategy` is `LOWEST_COST_WITH_MIN_ROAS`; sending it without `bidStrategy` is a 400. Sent to Meta as `bid_constraints.roas_average_floor` × 10000.\n\nKnown gap: a CBO campaign's ROAS floor lives on the campaign only (set via `POST /v1/ads/campaigns`). There is no supported way to set it while joining a CBO campaign here.\n"},"portfolioBidStrategyId":{"type":"string","pattern":"^\\d+$","description":"Google Search and Display only. Performance Max rejects portfolio bidding. Attach an existing portfolio bid strategy (numeric id from GET /v1/ads/bid-strategies) to the new campaign instead of a standard one. Exclusive with bidStrategy."},"targetImpressionShare":{"allOf":[{"$ref":"#/components/schemas/GoogleTargetImpressionShare"}],"description":"Google Search only. Target impression share bidding. Exclusive with bidStrategy, portfolioBidStrategyId and manualCpc; bidAmount is refused alongside it (the ceiling is maxCpc)."},"manualCpc":{"$ref":"#/components/schemas/GoogleManualCpc"},"networkSettings":{"allOf":[{"$ref":"#/components/schemas/GoogleNetworkSettings"}],"description":"Google Search only, when the call creates the campaign (400 with existingCampaignId or adSetId)."},"valueRuleSetId":{"type":"string","pattern":"^\\d+$","description":"Meta only (facebook, instagram; other platforms return 400). Value rule set\nto attach to the new ad set, from `/v1/ads/value-rule-sets`. Attachment is\ndriven by this id, so `valueRulesApplied` is optional alongside it.\n\nRejected with 400 in `adSetId` attach mode: that shape inherits the existing\nad set's attachment, so the field would be silently ignored. Use\n`PUT /v1/ads/ad-sets/{adSetId}` there instead.\n\nIgnored (stripped before the ad-set create) when `buyingType` is `RESERVED`:\nvalue rules only apply to auction ad sets on `LOWEST_COST_WITHOUT_CAP` or\n`COST_CAP`, and a Reach & Frequency reservation has no auction bid strategy.\n\nRead back with `GET /v1/ads/ad-sets/{adSetId}?fields=value_rule_set_id`; the\nattachment is not mirrored onto Zernio's ad documents.\n"},"valueRulesApplied":{"type":"boolean","description":"Meta only (facebook, instagram; other platforms return 400). Optional when\nattaching, and requires `valueRuleSetId`. `false` is REJECTED here with 400:\na newly created ad set has nothing to detach, so detaching lives on\n`PUT /v1/ads/ad-sets/{adSetId}`.\n"},"platformSpecificData":{"description":"Platform-specific options. The platform is derived from `accountId`; options for a different platform return a 400. LinkedIn (campaign bidding and delivery controls) and Meta (the bid trio) have options today.\n\n**Meta**\n\n- `bidStrategy`, `bidAmount` and `roasAverageFloor` may be sent here instead of at the root (the preferred home going forward). Sending them in BOTH places returns a 400 (`mutually_exclusive_fields`).\n- Sending any bid field in `adSetId` attach mode is a 400 (the ad set already has its bid).\n- `dailyMinSpendTarget` / `lifetimeMinSpendTarget` set the new ad set's minimum spend and live here only; also rejected in `adSetId` attach mode.\n","oneOf":[{"$ref":"#/components/schemas/LinkedInAdsPlatformData"},{"$ref":"#/components/schemas/MetaAdsPlatformData"}]},"dsaBeneficiary":{"type":"string","maxLength":100,"description":"Legal entity that benefits from the ad. Required when targeting EU users\n(EU DSA, Article 26). Optional if the ad account has a default beneficiary:\nset it once via `PATCH /v1/ads/accounts` or in Meta Ads Manager, and Meta\nfills it in whenever the field is omitted.\n"},"dsaPayor":{"type":"string","maxLength":100,"description":"Legal entity that pays for the ad. Can differ from `dsaBeneficiary`\n(for example, an agency paying for a client's ads). Same rules as\n`dsaBeneficiary`: required for EU targeting unless the ad account has\na default payor.\n"},"brandIdentity":{"type":"object","description":"TikTok only; non-TikTok platforms ignore this field. Synthetic Brand Identity used when the ad attributes to a CUSTOMIZED_USER (instead of a real TT_USER @username).\n\nRequired on the FIRST CUSTOMIZED_USER ad on a `tiktokads` SocialAccount with no cached identity. Omit it on later ads: the identity is cached on the account after first creation.\n\nAlternative: configure once via `PATCH /v1/connect/tiktok-ads`, then create ads without this field.\n","required":["displayName","imageUrl"],"properties":{"displayName":{"type":"string","minLength":1,"maxLength":40,"description":"Brand name shown above the ad on TikTok."},"imageUrl":{"type":"string","format":"uri","description":"Public URL of a square brand image (≥98×98 px, JPG/PNG). Used as the brand avatar on the ad."}}},"identityId":{"type":"string","description":"TikTok: the identity the ad runs as, from GET /v1/ads/tiktok-identities. Overrides the connected account's own identity; must be authorized on the advertiser."},"identityType":{"type":"string","enum":["TT_USER","CUSTOMIZED_USER","BC_AUTH_TT"],"description":"TikTok only. Forces the identity attribution on the ad:\n\n  - `TT_USER`: the posting account's open_id (real @username\n    branding). Requires a connected TikTok posting account\n    on the same profile.\n  - `CUSTOMIZED_USER`: synthetic Brand Identity (display\n    name + avatar). Requires a configured Brand Identity\n    (cached on the `tiktokads` SocialAccount via\n    `PATCH /v1/connect/tiktok-ads`) or an inline\n    `brandIdentity` to create one on the fly.\n\nWhen omitted, defaults to `TT_USER` if a posting account is\nconnected on this profile, else `CUSTOMIZED_USER`. Spark\nAds (`POST /v1/ads/boost`) always use `TT_USER` regardless\nof this field, because TikTok requires the original organic\npost's author identity for Spark.\n"},"smartPlus":{"type":"boolean","description":"TikTok only. Creates the ad as a TikTok Upgraded Smart+ campaign: TikTok automates targeting, bidding and delivery. Supported goals:\n\n- `conversions`: Smart+ Web Conversions.\n- `lead_generation`: Smart+ Lead Generation with a website form on `linkUrl` (TikTok Instant Forms not supported).\n- `app_promotion`: Smart+ App installs. The destination is the app store, so `linkUrl` is not used.\n\nThe web goals require `promotedObject.pixelId` AND `promotedObject.customEventType`; `app_promotion` requires `promotedObject.applicationId` instead.\n\nTargeting works like on any TikTok ad (defaults to `countries: [\"US\"]` when omitted), and TikTok automates delivery within it.\n\nThe budget lives on the Smart+ campaign (Campaign Budget Optimization). A `lifetime` budget without `endDate` ends 7 days after it starts. Smart+ needs `goal` sent; it is never inferred. Cannot be combined with `adSetId`.\n"},"userOs":{"type":"array","minItems":1,"items":{"type":"string","minLength":1},"description":"Meta only. Operating systems and version ranges, such as iOS_ver_14.0_and_above or Android. Emitted as user_os. May also be supplied inside targeting."},"userDevice":{"type":"array","minItems":1,"items":{"type":"string","minLength":1},"description":"Meta only. Device models such as iPhone. Emitted as user_device. May also be supplied inside targeting."},"isSkadnetworkAttribution":{"type":"boolean","description":"Meta app promotion only. Immutable campaign flag. Set true for iOS 14+ SKAdNetwork campaigns and supply promotedObject.applicationId plus promotedObject.objectStoreUrl. The campaign receives promotedObject only when this flag is true. Cannot be changed on an existing campaign."},"campaignAttribution":{"type":"string","enum":["AEM","SKADNETWORK"],"description":"Meta ad-set attribution. Required as SKADNETWORK for iOS 14+ app promotion or a SKAdNetwork campaign. Requires AUCTION buying. Standalone Meta ad-set creation is not supported; use this field on /v1/ads/create."},"promotedObject":{"$ref":"#/components/schemas/AdPromotedObject"}}},"examples":{"googleSearchPresenceOnly":{"summary":"Google Search campaign that reaches only people located in Lyon.","value":{"accountId":"69ce75d483e990e1c01ccfe4","adAccountId":"9122445560","name":"Lyon plumbing","goal":"traffic","campaignType":"search","budgetAmount":5,"budgetType":"daily","status":"PAUSED","headline":"Plumber in Lyon","body":"Same-day repairs across Lyon.","linkUrl":"https://example.com","keywords":["plombier lyon"],"cities":["1006410"],"locationTargetingType":"presence"}},"performanceMax":{"summary":"Paused Performance Max campaign.","value":{"accountId":"69ce75d483e990e1c01ccfe4","adAccountId":"9122445560","name":"Social publishing","campaignType":"pmax","budgetAmount":1,"budgetType":"daily","status":"PAUSED","validateOnly":true,"countries":["US"],"languages":["en"],"assetGroup":{"finalUrl":"https://zernio.com","headlines":["Schedule posts","One social API","Build with Zernio"],"longHeadline":"Schedule social content from your app with Zernio","descriptions":["Connect your social accounts.","Publish and manage social content through one API."],"businessName":"Zernio","images":{"landscape":["https://example.com/landscape.png"],"square":["https://example.com/square.png"],"logo":["https://example.com/logo.png"]}}}},"demandGen":{"summary":"Paused Demand Gen campaign with a multi-asset image ad.","value":{"accountId":"69ce75d483e990e1c01ccfe4","adAccountId":"9122445560","name":"Demand Gen launch","campaignType":"demand_gen","budgetAmount":10,"budgetType":"daily","validateOnly":true,"countries":["ES"],"languages":["es"],"demandGen":{"finalUrl":"https://zernio.com","businessName":"Zernio","headlines":["Schedule posts","One social API"],"descriptions":["Publish and manage social content through one API."],"callToAction":"Learn more","images":{"landscape":["https://example.com/landscape.png"],"square":["https://example.com/square.png"],"logo":["https://example.com/logo.png"]},"channels":["youtube_in_feed","youtube_shorts","discover","gmail"],"audience":{"userInterests":["92948"],"ageRanges":[{"min":25,"max":54}]}}}},"demandGenNewAdGroup":{"summary":"Add a paused ad group with its own audience and ad to an existing Demand Gen campaign.","value":{"accountId":"69ce75d483e990e1c01ccfe4","adAccountId":"9122445560","name":"Demand Gen, second audience","campaignType":"demand_gen","existingCampaignId":"23508518100","countries":["US"],"demandGen":{"adGroupName":"Returning visitors","finalUrl":"https://zernio.com","businessName":"Zernio","headlines":["Schedule posts"],"descriptions":["Publish everywhere from one API."],"images":{"square":["https://example.com/square.png"],"logo":["https://example.com/logo.png"]},"audience":{"userLists":["123456"]}}}},"demandGenNewAd":{"summary":"Add a paused video ad to an existing Demand Gen ad group.","value":{"accountId":"69ce75d483e990e1c01ccfe4","adAccountId":"9122445560","name":"Demand Gen video variant","campaignType":"demand_gen","adSetId":"191940825986","demandGen":{"finalUrl":"https://zernio.com","businessName":"Zernio","headlines":["Schedule posts"],"longHeadlines":["Schedule social posts from your app"],"descriptions":["Publish everywhere from one API."],"images":{"logo":["https://example.com/logo.png"]},"youtubeVideoIds":["dQw4w9WgXcQ"]}}},"demandGenCarousel":{"summary":"Paused Demand Gen campaign with a carousel ad.","value":{"accountId":"69ce75d483e990e1c01ccfe4","adAccountId":"9122445560","name":"Demand Gen carousel","campaignType":"demand_gen","budgetAmount":10,"budgetType":"daily","countries":["ES"],"demandGen":{"finalUrl":"https://zernio.com","businessName":"Zernio","headlines":["One social API"],"descriptions":["Publish everywhere from one API."],"images":{"logo":["https://example.com/logo.png"]},"carouselCards":[{"headline":"Schedule posts","images":{"square":"https://example.com/card-1.png"}},{"headline":"Read analytics","finalUrl":"https://zernio.com/pricing","images":{"square":"https://example.com/card-2.png"}}]}}},"appPromotion":{"value":{"accountId":"69fc524892b3d8e85f893e73","adAccountId":"act_757082720485182","name":"iOS app installs","goal":"app_promotion","isSkadnetworkAttribution":true,"campaignAttribution":"SKADNETWORK","buyingType":"AUCTION","billingEvent":"IMPRESSIONS","optimizationGoal":"APP_INSTALLS","promotedObject":{"applicationId":"123456789","objectStoreUrl":"https://apps.apple.com/us/app/id123456789"},"linkUrl":"https://apps.apple.com/us/app/id123456789","headline":"Install our app","body":"Get started today.","callToAction":"INSTALL_MOBILE_APP","imageUrl":"https://example.com/app.jpg","targeting":{"countries":["US"],"userOs":["iOS_ver_14.0_and_above"]},"tracking":{"urlTags":[{"key":"utm_content","value":"{{ad.id}}"}]},"budgetAmount":1,"budgetType":"daily","status":"PAUSED","validateOnly":true}},"retailPromotion":{"value":{"accountId":"69fc524892b3d8e85f893e73","adAccountId":"act_123456789","name":"Autumn promotion","goal":"traffic","budgetAmount":5,"budgetType":"daily","status":"PAUSED","headline":"Save on your next order","body":"Use SAVE20 at checkout.","callToAction":"SHOP_NOW","linkUrl":"https://example.com/shop","imageUrl":"https://example.com/ad.jpg","creativeFeatures":{"auto_promotion_tag":"OPT_OUT"}}}}}}},"responses":{"200":{"description":"validateOnly dry-run passed, nothing was created","content":{"application/json":{"schema":{"type":"object","properties":{"validateOnly":{"type":"boolean","description":"Always true in a validate-only response."},"appliedDefaults":{"$ref":"#/components/schemas/AdAppliedDefaults"},"results":{"type":"array","items":{"type":"object","properties":{"node":{"type":"string","enum":["campaign","adSet","creative","ad","performanceMaxCampaign","identity"],"description":"`identity` is TikTok only: the identity the ad would run as."},"status":{"type":"string","enum":["validated","skipped","unverified"]},"reason":{"type":"string","description":"Explanation for the node's result:\n\n- On skipped: why the node could not be validated.\n- On unverified: why the platform could not dry-run it although the other nodes passed (Meta), or what only a real create checks (TikTok).\n- On validated: what the dry run could not check, and what the request would do as sent. For example, a Performance Max validation with no location targeting reports here that the campaign would run worldwide."}}}},"message":{"type":"string"}}}}}},"201":{"description":"Ad(s) created","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Legacy + attach shapes: one ad returned.","properties":{"ad":{"$ref":"#/components/schemas/Ad"},"appliedDefaults":{"$ref":"#/components/schemas/AdAppliedDefaults"},"message":{"type":"string"},"recoveredWrites":{"$ref":"#/components/schemas/MetaRecoveredWrites"},"warnings":{"type":"array","items":{"type":"string"},"description":"Meta only, present only when needed.\n\nAn `activation_failed:` entry means Meta refused the final switch to ACTIVE. The entry names what was kept PAUSED (the ad, plus its ad set or campaign when Meta refused those) and what was switched ACTIVE, and quotes Meta's error and the status calls that switch the PAUSED ones on later.\n"}}},{"type":"object","description":"Multi-creative shape: N ads returned sharing platformCampaignId / platformAdSetId.","properties":{"ads":{"type":"array","items":{"$ref":"#/components/schemas/Ad"}},"platformCampaignId":{"type":"string"},"platformAdSetId":{"type":"string"},"appliedDefaults":{"$ref":"#/components/schemas/AdAppliedDefaults"},"message":{"type":"string"},"recoveredWrites":{"$ref":"#/components/schemas/MetaRecoveredWrites"},"warnings":{"type":"array","items":{"type":"string"},"description":"Meta only, present only when needed.\n\nAn `activation_failed:` entry means Meta refused the final switch to ACTIVE for the ads it names (or for their ad set or campaign). The entry names what was kept PAUSED and what was switched ACTIVE, and quotes Meta's error and the status calls that switch the PAUSED ones on later.\n"}}}]}}}},"400":{"x-summary":"Required fields are missing, values are invalid, or the platform rejected validation: fix the request and resend.","description":"Missing required fields, invalid values, non-Meta platform used with creatives[] / adSetId, or a Meta validateOnly validation failure (verbatim)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is blocked: enable the Ads add-on, add a card, select the ad account, or grant the user Advertise permission.","description":"Ads access required. Legacy plans need the Ads add-on; it is included by default on usage-based plans. Also returned with these codes:\n\n- `ads_allowance_exceeded`: the team has no payment method on file and has reached the 500 free live ads. Add a card to resume.\n- `ad_account_not_selected`: the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n- `ad_account_not_selected`, fix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n- `insufficient_permissions`: the Facebook user behind the connection's token lacks the Advertise permission on the Meta ad account, or the token lacks `ads_management` (Meta subcode 2490585, 2490591 or 4841020; see `ErrorResponse.details`).\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"x-summary":"The ad account is not ready for this ad: connect the ads account, fix its status, or meet the platform prerequisites.","description":"Platform ads connection required (TikTok Ads, X Ads) or missing linked account. Also returned:\n\n- With code `ad_account_unusable`: Meta refuses writes on the ad account because its status is ineligible to manage ads (see `ErrorResponse.details`).\n- On Reddit: `video_views` without a video, or an ad account with no pixel or no profile.\n- On Reddit, with code `invalid_resource_state`: a pixel that never received the event the ad group optimizes toward.\n"},"429":{"$ref":"#/components/responses/MetaAdAccountWriteLimited"},"501":{"x-summary":"The platform does not support the requested option: remove it or change the ad shape, then resend.","description":"The requested option is not supported on this platform: `validateOnly` outside Meta,\nTikTok, ChatGPT and Google Performance Max / Demand Gen, or a shape the adapter does not implement. Carries code\n`feature_not_available`.\n"},"502":{"x-summary":"The platform rejected the request or produced no media, such as a missing video poster: supply `video.thumbnailUrl` and retry.","description":"The platform rejected the request, or failed to produce media the ad needs (e.g. Meta generated no poster for an uploaded video when no `video.thumbnailUrl` was supplied). An upstream 4xx status is forwarded instead of 502.\n\n- Inspect `platformError` for the upstream payload.\n- Failures we raise carry a `reason`; a payload forwarded verbatim from Meta may not.\n- On the `creatives[]` shape, a missing poster also carries `creativeIndex` and `videoUrl` to identify the entry.\n- On Meta, `details` names the failing `stage`, the `adAccountId` and every created object with its cleanup result (see `ErrorResponse.details`). An `unconfirmedWrite` there means Meta did not confirm a create and Zernio did not retry it.\n"},"503":{"x-summary":"An upstream service is temporarily unavailable: retry after the indicated delay and clean up any leftover objects named in `details`.","description":"An upstream service is temporarily unavailable (most often the connection to Meta dropped mid-request). Retry after the indicated delay.\n\nOn Meta, `details` carries the same `stage`, `adAccountId` and `createdObjects` as a 502, and the message names every `left_behind` object. In `createdObjects`:\n\n- `deleted`: Zernio deleted the object.\n- `left_behind`: still exists on the ad account because cleanup could not delete it (Meta refused the delete, or the delete hit a network error). Delete a left-behind video with `DELETE /v1/ads/videos/{id}` and the other objects in Meta Ads Manager.\n- `kept`: images are never deleted, because an image hash is shared by every upload of the same file.\n\nAn empty `left_behind` list is not a guarantee: when Meta created media but its answer never arrived (a dropped connection or a 5xx on the first step of a video upload), Zernio never learned the id and cannot list or delete it.\n","headers":{"Retry-After":{"schema":{"type":"integer","example":5},"description":"Minimum delay in seconds before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Temporary connection issue while reaching an upstream service. Please retry the request. Zernio could not delete what this request created before failing (video 1234567890123456), so it is still on Meta: delete the video with DELETE /v1/ads/videos/1234567890123456.","type":"api_error","code":"temporarily_unavailable","details":{"stage":"media","adAccountId":"act_123","createdObjects":[{"type":"campaign","id":"120210000000000001","cleanup":"deleted"},{"type":"video","id":"1234567890123456","cleanup":"left_behind"},{"type":"image","id":"4f1c2e9b0a7d3e6f8b2c1d0e9f8a7b6c","cleanup":"kept"}]}}}}}}}},"/v1/ads/leads":{"get":{"x-resource-group":"contacts","operationId":"listLeads","tags":["Lead Gen"],"x-platforms":["meta","linkedin"],"summary":"List submitted leads","description":"Lists the leads submitted through your Meta or LinkedIn lead forms, newest first.\n\nReturns submitted Lead Gen leads for your team, newest-first, with keyset pagination on `cursor`. Requires the Ads add-on.\n\n### Meta (default)\n\nLeads are served from the persisted cache, ingested in real time from the `leadgen` webhook.\n\n### LinkedIn\n\nWhen `accountId` is a LinkedIn ads account, `adAccountId` is required. Leads are fetched live from LinkedIn's `leadFormResponses`: LinkedIn has no webhook and enforces 90-day retention, so nothing is persisted.\n\nReading LinkedIn responses needs the `r_marketing_leadgen_automation` permission. Accounts connected before it was added must reconnect.\n","parameters":[{"name":"formId","in":"query","schema":{"type":"string"},"description":"Filter to a single lead form."},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Filter to a single connected account. LinkedIn ads accounts switch to the live fetch."},{"name":"accountIds","in":"query","schema":{"type":"string"},"description":"Meta only. Comma-separated connected account ids, to list several accounts at once. Without accountId or accountIds every account of the team is listed."},{"name":"status","in":"query","schema":{"type":"string","example":"new,contacted"},"description":"Meta only. Comma-separated lead statuses: new, contacted, unreachable, qualified, converted, disqualified."},{"name":"campaignId","in":"query","schema":{"type":"string"},"description":"Meta only. The platform campaign id the lead came from."},{"name":"platform","in":"query","schema":{"type":"string","enum":["meta","linkedin"]},"description":"meta skips the LinkedIn live fetch; linkedin requires accountId to be a LinkedIn ads connection (400 otherwise)."},{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Meta only. Case-insensitive text search over the lead's answers and the form name."},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"LinkedIn only: the LinkedIn ad account id whose responses to read (owner-scoped finder)."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"since","in":"query","schema":{"type":"integer","minimum":1,"maximum":253402300799,"example":1757404800},"description":"Unix seconds; only leads created at/after this timestamp. Millisecond timestamps return 400 with instructions to divide by 1000."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Keyset cursor from a previous response's pagination.cursor (Meta: AdLead id; LinkedIn: numeric start offset)."}],"responses":{"200":{"description":"Lead list.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"leads":{"type":"array","items":{"$ref":"#/components/schemas/AdLead"}},"pagination":{"type":"object","properties":{"hasMore":{"type":"boolean"},"cursor":{"type":["string","null"]}}},"meta":{"type":"object","properties":{"lastCheckedAt":{"type":["string","null"],"format":"date-time","description":"Meta only, present when `accountId` is passed: when Zernio last re-read the Page's forms from Meta to catch leads the webhook missed. Null when no leads matched or before the first pass."},"lastUpdated":{"type":"string","format":"date-time"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads add-on required."},"502":{"$ref":"#/components/responses/UpstreamFailure"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/v1/ads/leads/counts":{"get":{"x-resource-group":"contacts","operationId":"countLeads","tags":["Lead Gen"],"x-platforms":["meta"],"summary":"Count leads by status","description":"Counts your team's stored Meta leads per status, for a status filter or a \"new leads\" badge.\n\nEvery status is present, with 0 when no lead has it. Requires the Ads add-on.\n","parameters":[{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Count one connected account only."},{"name":"campaignId","in":"query","schema":{"type":"string"},"description":"The platform campaign id the leads came from."}],"responses":{"200":{"description":"Lead counts.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"counts":{"type":"object","properties":{"new":{"type":"integer"},"contacted":{"type":"integer"},"unreachable":{"type":"integer"},"qualified":{"type":"integer"},"converted":{"type":"integer"},"disqualified":{"type":"integer"}}},"total":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads add-on required."}}}},"/v1/ads/leads/{id}":{"patch":{"x-resource-group":"contacts","operationId":"updateLead","tags":["Lead Gen"],"x-platforms":["meta"],"summary":"Update a lead's status","description":"Sets the status of a Meta lead (and optionally its value) so you can track it from lead to sale.\n\n`{id}` is the Zernio lead id (`id` on `GET /v1/ads/leads`, `leadId` on `GET /v1/ads/lead-forms/{formId}/leads`) or the Meta `leadgenId` together with `accountId` in the body. Requires the Ads add-on.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Zernio lead id, or the Meta leadgenId (then accountId is required)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["new","contacted","unreachable","qualified","converted","disqualified"]},"value":{"type":"number","minimum":0,"description":"Deal value; requires currency."},"currency":{"type":"string","example":"EUR","description":"ISO 4217 code."},"accountId":{"type":"string","description":"Required when `{id}` is a Meta leadgenId: the facebook or metaads account that received the lead."}}}}}},"responses":{"200":{"description":"The updated lead.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"lead":{"$ref":"#/components/schemas/AdLead"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads add-on required."},"404":{"description":"Lead not found or not accessible."}}}},"/v1/ads/lead-forms":{"get":{"x-resource-group":"ads","operationId":"listLeadForms","tags":["Lead Gen"],"x-platforms":["meta","linkedin"],"summary":"List lead forms","description":"Lists the lead forms on a Facebook Page or LinkedIn Company Page.\n\nMeta: forms on the connected Facebook Page. Pass either the `metaads` ads connection (the Page is taken from the Facebook account linked to it) or the Facebook account itself. LinkedIn: forms owned by the ad account's Company Page. Pass `adAccountId` (LinkedIn forms are org-owned). Requires the Ads add-on.\n","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected Meta ads, Facebook, Instagram or LinkedIn ads account ID.\n\n- Meta ads connection: resolves its Page through the Facebook account linked to the same profile.\n- Instagram account: uses the Page its ads run under (its own linked Page, else the Facebook or business-login Meta ads account on the same profile)."},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"LinkedIn only: the LinkedIn ad account id (used to resolve the owning organization). Required for LinkedIn."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Forms list.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"forms":{"type":"array","items":{"type":"object"}},"pagination":{"type":"object","properties":{"hasMore":{"type":"boolean"},"cursor":{"type":["string","null"]}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads add-on required."},"409":{"$ref":"#/components/responses/AccountDisconnected"}}},"post":{"x-resource-group":"ads","operationId":"createLeadForm","tags":["Lead Gen"],"x-platforms":["meta","linkedin"],"summary":"Create a lead form","description":"Creates a lead form on a Facebook Page or LinkedIn Company Page to collect contact details from ads.\n\nThe form content goes inside `platformSpecificData` for both platforms (the shape is selected by the accountId's platform). Requires the Ads add-on.\n\nNOT idempotent: a retry creates a second form.\n\n### Meta\n\nCreated on the connected Facebook Page (POST /{page-id}/leadgen_forms). `accountId` may be:\n\n- the `metaads` ads connection (its Page comes from the Facebook account linked to the same profile)\n- an Instagram account (the Page its ads run under: its own linked Page, else the Facebook or business-login Meta ads account on the same profile)\n- the Facebook account itself\n\nThe old top-level Meta fields (questions, thankYou*, contextCard, …) are DEPRECATED but still accepted while platformSpecificData is absent. Mixing both shapes is a 400.\n\nthankYouEnableMessenger, isPhoneSmsVerifyEnabled and customDisclaimer are accepted only inside platformSpecificData (top-level is a 400).\n\nMeta prefilled question types (EMAIL, PHONE, FULL_NAME, …) must omit label/key; CUSTOM questions require both.\n\n### LinkedIn\n\nCreated on the ad account's Company Page. LinkedIn exposes only free-text and multiple-choice questions via API (prefilled-from-profile fields are Campaign Manager UI-only).\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","name","privacyPolicyUrl"],"properties":{"accountId":{"type":"string"},"name":{"type":"string","maxLength":200},"questions":{"type":"array","minItems":1,"deprecated":true,"description":"Deprecated (Meta legacy shape): use platformSpecificData.questions.","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"EMAIL, PHONE, FULL_NAME, FIRST_NAME, LAST_NAME, CUSTOM, …"},"key":{"type":"string","description":"CUSTOM questions only."},"label":{"type":"string","description":"CUSTOM questions only."},"options":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"inline_context":{"type":"string"}}}},"privacyPolicyUrl":{"type":"string","format":"uri"},"privacyPolicyLinkText":{"type":"string","maxLength":70,"deprecated":true,"description":"Deprecated: use platformSpecificData.privacyPolicyLinkText."},"followUpActionUrl":{"type":"string","format":"uri","deprecated":true,"description":"Deprecated: use platformSpecificData.followUpActionUrl."},"locale":{"type":"string","example":"EN_US","deprecated":true,"description":"Deprecated: use platformSpecificData.locale."},"thankYouTitle":{"type":"string","deprecated":true,"description":"Deprecated: use platformSpecificData.thankYouTitle."},"thankYouBody":{"type":"string","deprecated":true,"description":"Deprecated: use platformSpecificData.thankYouBody."},"thankYouButtonText":{"type":"string","deprecated":true,"description":"Deprecated: use platformSpecificData.thankYouButtonText."},"thankYouButtonType":{"type":"string","example":"VIEW_WEBSITE","deprecated":true,"description":"Deprecated: use platformSpecificData.thankYouButtonType."},"thankYouWebsiteUrl":{"type":"string","format":"uri","deprecated":true,"description":"Deprecated: use platformSpecificData.thankYouWebsiteUrl."},"isOptimizedForQuality":{"type":"boolean","deprecated":true,"description":"Deprecated: use platformSpecificData.isOptimizedForQuality."},"platformSpecificData":{"description":"Form content; the shape is selected by the accountId's platform. Unknown fields are a 400 (strict-parsed).","oneOf":[{"type":"object","title":"MetaLeadFormPlatformData","required":["questions"],"properties":{"questions":{"type":"array","minItems":1,"items":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"EMAIL, PHONE, FULL_NAME, FIRST_NAME, LAST_NAME, CUSTOM, …"},"key":{"type":"string","description":"CUSTOM questions only."},"label":{"type":"string","description":"CUSTOM questions only."},"options":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"inline_context":{"type":"string"}}}},"privacyPolicyLinkText":{"type":"string","maxLength":70},"followUpActionUrl":{"type":"string","format":"uri"},"locale":{"type":"string","example":"EN_US"},"thankYouTitle":{"type":"string"},"thankYouBody":{"type":"string"},"thankYouButtonText":{"type":"string"},"thankYouButtonType":{"type":"string","example":"VIEW_WEBSITE","description":"Meta thank_you_page.button_type. Defaults to VIEW_WEBSITE. Case-insensitive, sent to Meta in uppercase. CALL_BUSINESS requires businessPhoneNumber and countryCode (a 400 otherwise). Meta rejects MESSAGE_BUSINESS on thank-you pages with (#100) This button type is not yet supported for Thank You Page."},"businessPhoneNumber":{"type":"string","example":"+12025550123","description":"International E.164 number the CALL_BUSINESS thank-you button dials (Meta thank_you_page.business_phone_number).\n\n- Must start with + and the country calling code matching countryCode. Spaces, dashes, dots and parentheses are stripped; a local number such as 2025550123 is a 400.\n- Required when thankYouButtonType is CALL_BUSINESS; a 400 with any other button type.\n- Accepted only inside platformSpecificData; a top-level businessPhoneNumber is a 400."},"countryCode":{"type":"string","pattern":"^[A-Za-z]{2}$","example":"US","description":"ISO 3166-1 alpha-2 country of businessPhoneNumber (Meta thank_you_page.country_code), sent in uppercase. Required when thankYouButtonType is CALL_BUSINESS and a 400 with any other button type. Accepted only inside platformSpecificData: a top-level countryCode is a 400."},"thankYouWebsiteUrl":{"type":"string","format":"uri"},"thankYouEnableMessenger":{"type":"boolean","default":false,"description":"Sent as Meta thank_you_page.enable_messenger (boolean). Accepted only inside platformSpecificData: a top-level thankYouEnableMessenger is a 400."},"isOptimizedForQuality":{"type":"boolean","description":"Set true for a higher-intent form (adds a review step before submit)."},"isPhoneSmsVerifyEnabled":{"type":"boolean","default":false,"description":"Requires the lead to verify their phone number over SMS before the form submits (Meta is_phone_sms_verify_enabled). Only meaningful on a form with a PHONE question.\n\nMeta can restrict this parameter to apps holding a capability. When it does, the create fails with a 422 naming platformSpecificData.isPhoneSmsVerifyEnabled, and the toggle must then be set in Meta's form builder."},"blockDisplayForNonTargetedViewer":{"type":"boolean"},"questionPageCustomHeadline":{"type":"string"},"contextCard":{"type":"object","properties":{"title":{"type":"string"},"content":{"type":"array","items":{"type":"string"}},"style":{"type":"string","enum":["LIST_STYLE","PARAGRAPH_STYLE"]},"buttonText":{"type":"string"},"coverPhoto":{"type":"string","format":"uri","description":"Direct public JPEG or PNG image URL, up to 5 MB. Uploaded as an unpublished Page photo and attached to the form. Redirects, Ad Image hashes and IDs are not supported."}}},"customDisclaimer":{"type":"object","required":["title","body","checkboxes"],"description":"Consent section with checkboxes (Meta custom_disclaimer). Each lead's answers come back on the lead, and a lead_received workflow only messages leads that ticked its consentCheckboxKey.","properties":{"title":{"type":"string","example":"WhatsApp"},"body":{"type":"string","example":"Acme can contact you on WhatsApp about your request."},"checkboxes":{"type":"array","minItems":1,"items":{"type":"object","required":["key","text"],"properties":{"key":{"type":"string","example":"whatsapp_optin"},"text":{"type":"string","example":"I agree to receive WhatsApp messages from Acme"},"isRequired":{"type":"boolean","default":false},"isCheckedByDefault":{"type":"boolean","default":false}}}}}}}},{"type":"object","title":"LinkedInLeadFormPlatformData","required":["adAccountId","headline","description","questions"],"properties":{"adAccountId":{"type":"string","description":"LinkedIn ad account id (resolves the owning organization)."},"headline":{"type":"string","maxLength":255},"description":{"type":"string","maxLength":1500},"state":{"type":"string","enum":["DRAFT","PUBLISHED"],"description":"Defaults to DRAFT."},"locale":{"type":"object","properties":{"country":{"type":"string"},"language":{"type":"string"}}},"consents":{"type":"array","items":{"type":"object","required":["description"],"properties":{"description":{"type":"string"},"required":{"type":"boolean","description":"Whether the viewer must tick this consent to submit. Defaults to false.","default":false}}}},"questions":{"type":"array","minItems":1,"items":{"oneOf":[{"type":"object","required":["kind","name","question"],"properties":{"kind":{"type":"string","enum":["text"]},"name":{"type":"string"},"question":{"type":"string"},"required":{"type":"boolean"},"responseEditable":{"type":"boolean"},"maxResponseLength":{"type":"integer","description":"Defaults to 300 on LinkedIn's side."}}},{"type":"object","required":["kind","name","question","choices"],"properties":{"kind":{"type":"string","enum":["multipleChoice"]},"name":{"type":"string"},"question":{"type":"string"},"required":{"type":"boolean"},"responseEditable":{"type":"boolean"},"choices":{"type":"array","minItems":1,"items":{"type":"object","required":["id","text"],"properties":{"id":{"type":"integer"},"text":{"type":"string"}}}}}}]}}}}]}}}}}},"responses":{"200":{"description":"Created form.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"form":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: enable Ads access or add the account to the connection's selection.","description":"Forbidden. One of:\n\n- Ads add-on required.\n- Code `ad_account_not_selected`: the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected."},"409":{"$ref":"#/components/responses/AccountDisconnected"},"422":{"x-summary":"Meta rejected the lead form: remove the field the response names, such as the phone verification option, and retry.","description":"Meta rejected the lead form. Code 3 is Meta's generic app-capability error and does not name a field; when the request set isPhoneSmsVerifyEnabled, the response names that field as the one to drop first."}}}},"/v1/ads/lead-forms/{formId}":{"get":{"x-resource-group":"ads","operationId":"getLeadForm","tags":["Lead Gen"],"x-platforms":["meta","linkedin"],"summary":"Get a lead form","description":"Shows a lead form in full, including its questions and thank-you page.\n\nReturns the full form, including the thank-you page, so a form can be diffed against what was created. Meta forms are scoped to the Page the accountId manages: a form on any other Page is a 404, never a read.\n","parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"},"description":"Numeric form id (Meta leadgen_form id or LinkedIn leadForm id)."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected Meta ads, facebook, instagram or linkedin ads account id (selects the platform).\n\n- Meta ads connection: resolves its Page through the Facebook account linked to the same profile.\n- Instagram account: uses the Page its ads run under (its own linked Page, else the Facebook or business-login Meta ads account on the same profile)."},{"name":"fields","in":"query","schema":{"type":"string","maxLength":2000},"description":"Meta only. A Graph field selection passed through verbatim to GET /{form-id}, replacing the default projection, so fields Meta adds later are reachable without an API change.\n\n- Field names, commas and {} expansion only. Anything else (Graph field modifiers such as .limit(), or characters that could open another query parameter) is a 400.\n- Unknown field names are rejected by Meta as a 400.\n- Ownership of the form is verified before the selection runs, so this cannot reach any Page but the one accountId manages.\n","example":"name,thank_you_page{title,body,button_type,website_url}"}],"responses":{"200":{"x-summary":"The lead form metadata: Meta forms use the Meta lead form shape and LinkedIn forms use their own shape.","description":"Form metadata. Meta forms follow MetaLeadForm; LinkedIn forms return LinkedIn's own adForm shape.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"form":{"oneOf":[{"$ref":"#/components/schemas/MetaLeadForm"},{"type":"object"}]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No lead form with that id on the Page this account manages."},"409":{"$ref":"#/components/responses/AccountDisconnected"}}},"delete":{"x-resource-group":"ads","operationId":"archiveLeadForm","tags":["Lead Gen"],"x-platforms":["meta","linkedin"],"summary":"Archive a lead form","description":"Archives a lead form so it can no longer be used (neither Meta nor LinkedIn allows deleting one).\n\nNeither platform hard-deletes a form; this archives it (Meta status=ARCHIVED; LinkedIn state=ARCHIVED via PARTIAL_UPDATE). Meta forms must belong to the Page the accountId manages.\n","parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"},"description":"Numeric form id (Meta leadgen_form id or LinkedIn leadForm id)."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected Meta ads, facebook, instagram or linkedin ads account id (selects the platform).\n\n- A Meta ads connection resolves its Page through the Facebook account linked to the same profile.\n- An Instagram account uses the Page its ads run under: its own linked Page, else the Facebook or business-login Meta ads account on the same profile."}],"responses":{"200":{"description":"Archived.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"formId":{"type":"string"},"archived":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"description":"No lead form with that id on the Page this account manages."},"409":{"$ref":"#/components/responses/AccountDisconnected"}}}},"/v1/ads/lead-forms/{formId}/leads":{"get":{"x-resource-group":"contacts","operationId":"listFormLeads","tags":["Lead Gen"],"x-platforms":["meta"],"summary":"List leads for a single form","description":"Lists the leads submitted through one Meta lead form.\n\nIt serves persisted leads (ingested via the leadgen webhook) when available, falling back to a live Graph read.\n\n### Accounts\n\nAccepts either of these with leads_retrieval access to the form:\n\n- a Facebook account\n- a metaads business-login account, which uses its system-user token without a posting parent\n\n### Freshness\n\nPersisted leads arrive in real time through Meta's webhook. A background pass re-reads every Page from Meta to catch the leads the webhook misses: every 15 minutes for Pages that received a lead in the last 7 days.\n\n`meta.lastCheckedAt` says when that pass last ran, so polling this endpoint faster than that returns nothing new. Subscribe to the `lead.received` webhook instead.\n\nThe live Graph read is cached for 5 minutes, and `meta.lastCheckedAt` is when it was read.\n","parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"since","in":"query","schema":{"type":"integer"},"description":"Unix seconds."}],"responses":{"200":{"description":"Leads for the form.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"leads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Meta leadgenId."},"leadId":{"type":"string","description":"Zernio lead id, for PATCH /v1/ads/leads/{id}. Only on persisted leads."},"status":{"type":"string","description":"Lead status (see PATCH /v1/ads/leads/{id}). Only on persisted leads."},"createdTime":{"type":["string","null"]},"adId":{"type":["string","null"]},"formId":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"fieldData":{"type":"array","items":{"type":"object"}},"consents":{"$ref":"#/components/schemas/AdLeadConsents"}}}},"pagination":{"type":"object","properties":{"hasMore":{"type":"boolean"},"cursor":{"type":["string","null"]}}},"meta":{"type":"object","properties":{"platform":{"type":"string","example":"facebook"},"accountId":{"type":"string"},"formId":{"type":"string"},"source":{"type":"string","enum":["persisted","live"],"description":"persisted: leads stored from the webhook and the reconcile pass. live: read from Meta because none are stored for this form yet."},"lastCheckedAt":{"type":["string","null"],"format":"date-time","description":"When Zernio last read this form's leads from Meta. For persisted leads, the last reconcile pass for the Page (null before the first one). For live reads, when the cached Graph read was made."},"lastUpdated":{"type":"string","format":"date-time"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountDisconnected"}}}},"/v1/ads/lead-forms/{formId}/test-leads":{"post":{"x-resource-group":"contacts","operationId":"createTestLead","tags":["Lead Gen"],"x-platforms":["meta"],"summary":"Create a test lead","description":"Submits a test lead to a Meta lead form so you can check your lead retrieval without running ads.\n\nSubmits a test lead against the form (POST /{form-id}/test_leads) to exercise retrieval without waiting for real ad impressions. Meta allows one test lead per form at a time.\n","parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","fieldData"],"properties":{"accountId":{"type":"string"},"fieldData":{"type":"array","minItems":1,"items":{"type":"object","required":["name","values"],"properties":{"name":{"type":"string"},"values":{"type":"array","items":{"type":"string"},"minItems":1}}}}}}}}},"responses":{"200":{"description":"Test lead created.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"testLead":{"type":"object","properties":{"id":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/AccountDisconnected"}}},"delete":{"x-resource-group":"contacts","operationId":"deleteTestLead","tags":["Lead Gen"],"x-platforms":["meta"],"summary":"Delete a test lead","description":"Deletes the test lead on a Meta lead form so you can submit a new one (Meta allows only one at a time).\n\nRemoves a test lead created for the form (DELETE /{leadgen_id}). Meta keeps one test lead per form and refuses a second until the first is gone.\n\n- The same test lead appears in Meta's Lead Ads Testing Tool.\n- Meta only deletes test leads; a real lead is refused.\n","parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"The facebook or metaads account whose Page owns the form."},{"name":"leadId","in":"query","required":false,"schema":{"type":"string"},"description":"The test lead id returned by createTestLead (or shown in the Testing Tool). Omitted = the test lead currently on the form."}],"responses":{"200":{"description":"Test lead deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"deleted":{"type":"array","items":{"type":"string"},"description":"Ids of the test leads removed."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"The form has no test lead."},"409":{"$ref":"#/components/responses/AccountDisconnected"}}}},"/v1/ads/images":{"post":{"x-resource-group":"ads","operationId":"uploadAdImage","tags":["Ad Creatives"],"x-platforms":["meta"],"summary":"Upload an ad image from base64","description":"Uploads an image file to a Meta ad account's library, for creatives that are not hosted at a public URL.\n\nReturns the image `hash` (Meta's identifier for\nthe asset) and the Meta-hosted `url`, which can be used directly as `imageUrl` on the\ncreate endpoints. Max 30 MB decoded.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","adAccountId","imageBase64"],"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id (posting or ads variant); its platform decides where the campaign is created."},"adAccountId":{"type":"string","description":"Platform ad account id (Meta act_<n>, Google customer id, LinkedIn account id, ...)."},"imageBase64":{"type":"string","description":"Raw base64 image bytes, or a full data URL (the data:image/...;base64, prefix is stripped)."},"filename":{"type":"string","description":"Optional filename shown in Meta's image library. Defaults to ad_image.jpg."}}}}}},"responses":{"201":{"description":"Image uploaded","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"image":{"type":"object","properties":{"hash":{"type":"string","description":"Meta image hash, reusable wherever image_hash is accepted."},"url":{"type":"string","description":"Meta-hosted image URL; usable as imageUrl on the create endpoints."}}}}}}}},"400":{"description":"Invalid input, or Meta rejected the image"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"},"502":{"x-summary":"Meta accepted the request but failed to produce the image, for example from an upload or processing timeout.","description":"Meta accepted the request then failed to produce the media (upload session, chunk transfer, processing timeout, or a response with no image hash). Inspect `platformError.reason`."}}},"get":{"x-resource-group":"ads","operationId":"listAdImages","tags":["Ad Creatives"],"x-platforms":["meta"],"summary":"Ad image library","description":"Lists the images in a Meta ad account's library so you can reuse one in a creative.\n\nLists the ad account's image library (Meta's `/act_X/adimages`), rows returned verbatim.\nThe default projection covers hash, url, name, dimensions and status; `fields` is a\nraw-passthrough override. Any `hash` here is reusable wherever Meta accepts\n`image_hash` (e.g. `imageHash` on POST /v1/ads/creatives).","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"Meta ad account id (act_<n>)."},{"name":"fields","in":"query","schema":{"type":"string","example":"hash,url,name,width,height,status"},"description":"Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers, so a nested edge can be paged explicitly: without a .limit() modifier the expansion runs at the Meta default page size and the tail is dropped silently."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Rows per page"},{"name":"after","in":"query","schema":{"type":"string"},"description":"Cursor from paging.after of the previous page."}],"responses":{"200":{"description":"Ad images (raw Meta shape)","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"data":{"type":"array","items":{"type":"object","description":"Raw Meta ad image row (hash, url, name, width, height, status)."}},"paging":{"type":"object","properties":{"after":{"type":["string","null"],"description":"Cursor for the next page; null when exhausted."}}}}}}}},"400":{"description":"Invalid input, or Meta rejected the query"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/videos":{"post":{"x-resource-group":"ads","operationId":"uploadAdVideo","tags":["Ad Creatives"],"x-platforms":["meta"],"summary":"Upload an ad video","description":"Uploads a video to a Meta ad account from a URL or file, so you can preview it or use it in ads before any ad exists.\n\nThis is a standalone ad-video upload (parallel to POST /v1/ads/images). A video creative can then be rendered via POST /v1/ads/preview or attached via `video.id` on POST /v1/ads/create before an ad exists.\n\n### Input\n\nExactly one is required:\n\n- `videoUrl`: an https URL we download server-side (SSRF-guarded).\n- `videoBase64`: raw bytes. Capped by Vercel's body limit, around 4.5 MB payload in practice, so larger videos must come via `videoUrl`.\n\n### Response\n\nReturns the Meta `video.id` (reusable wherever `video.id` is accepted) plus Meta's auto-generated poster URL when available.\n\nBy default the endpoint waits until Meta reports the video ready and answers 201. Chunked upload + transcode can take minutes; the handler runs up to 800 s.\n\n### Async mode\n\nSend `async: true` to get a 202 as soon as Meta has accepted the bytes, with `video.status: processing`. Then either:\n\n- poll `GET /v1/ads/videos/{videoId}` until `status` is `ready`, or\n- subscribe to the `ad.video.processed` webhook.\n\nA create call that references the video while it is still processing waits up to 30 s, then answers 409 `invalid_resource_state` naming the status endpoint.\n\nWith `videoUrl` the download and byte transfer still happen inside the request; only Meta's transcode is skipped.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","adAccountId"],"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id (posting or ads variant); its platform decides where the campaign is created."},"adAccountId":{"type":"string","description":"Platform ad account id (Meta act_<n>, Google customer id, LinkedIn account id, ...)."},"videoUrl":{"type":"string","description":"Public https URL of the video; downloaded server-side (SSRF-guarded) before chunked upload. Provide exactly one of videoUrl or videoBase64."},"videoBase64":{"type":"string","description":"Raw base64 video bytes, or a full data URL (the data:video/...;base64, prefix is stripped). Capped by Vercel's body limit (~4.5 MB payload). Provide exactly one of videoUrl or videoBase64."},"filename":{"type":"string","maxLength":255,"description":"Optional file name, sent to Meta as the video's name and title so it shows and is searchable in the Ads Manager media library. Applies to both videoUrl and videoBase64. Without it (and without name), a videoUrl upload is named after the last path segment of the URL."},"name":{"type":"string","maxLength":255,"description":"Optional video name shown in the Ads Manager media library. Takes precedence over filename."},"async":{"type":"boolean","default":false,"description":"true: answer 202 once Meta accepts the upload instead of waiting for processing. Poll GET /v1/ads/videos/{videoId} or subscribe to ad.video.processed."}}}}}},"responses":{"201":{"description":"Video uploaded and ready","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"video":{"type":"object","properties":{"id":{"type":"string","description":"Meta video id, reusable as video.id on POST /v1/ads/create and inside POST /v1/ads/preview creativeSpec."},"status":{"type":"string","enum":["ready"]},"thumbnailUrl":{"type":["string","null"],"description":"Meta-hosted poster URL if available; null when Meta has not produced a poster yet."}}}}}}}},"202":{"description":"async: true. Meta accepted the upload and is processing it","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"video":{"type":"object","properties":{"id":{"type":"string","description":"Meta video id. Usable as video.id once GET /v1/ads/videos/{videoId} reports ready."},"status":{"type":"string","enum":["processing"]},"thumbnailUrl":{"type":["string","null"],"description":"Always null on 202; read it from GET /v1/ads/videos/{videoId} once ready."}}}}}}}},"400":{"description":"Invalid input, or Meta rejected the upload"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"},"502":{"x-summary":"Meta accepted the upload but failed to produce the video, such as from a chunk transfer or processing timeout.","description":"Meta accepted the request then failed to produce the media (upload session, chunk transfer, processing timeout, or a response with no video id). Inspect `platformError.reason`."}}},"get":{"x-resource-group":"ads","operationId":"listAdVideos","tags":["Ad Creatives"],"x-platforms":["meta"],"summary":"Ad video library","description":"Lists the videos in a Meta ad account's library, including ones uploaded elsewhere, so you can reuse one across ads.\n\nIt lists the ad account's video library (Meta's `/act_X/advideos`), rows returned verbatim. The default projection covers id, title, status, poster frames, length and `source` (the playable MP4). `fields` is a raw-passthrough override.\n\nAny `id` here is reusable as `video.id` on the create endpoints, so N ads that differ only in copy share one upload.\n\n### Previewing with `source`\n\n`source` lets you PLAY a video before picking it, which a poster frame alone can't settle when several videos share a first frame.\n\nIt is a signed CDN URL that EXPIRES, so treat it as good for preview at selection time only. Never persist it; re-list to get a fresh one.\n\n### Videos uploaded elsewhere\n\nThis is the only way to reach a video uploaded OUTSIDE Zernio (Ads Manager, another tool). Videos we uploaded also come back as `creative.videoId` on GET /v1/ads.\n\n### Readiness and uploads\n\nMeta transcodes asynchronously, so a row is only usable once `status.video_status` reads `ready`.\n\nUpload a new video via POST /v1/ads/videos, or inline via `video.url` on POST /v1/ads/create.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"Meta ad account id (act_<n>)."},{"name":"fields","in":"query","schema":{"type":"string","example":"id,title,status,thumbnails,length"},"description":"Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers, so a nested edge can be paged explicitly: without a .limit() modifier the expansion runs at the Meta default page size and the tail is dropped silently."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Rows per page"},{"name":"after","in":"query","schema":{"type":"string"},"description":"Cursor from paging.after of the previous page."}],"responses":{"200":{"description":"Ad videos (raw Meta shape)","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"data":{"type":"array","items":{"type":"object","description":"Raw Meta ad video row (id, title, status, picture, thumbnails, length, source)."}},"paging":{"type":"object","properties":{"after":{"type":["string","null"],"description":"Cursor for the next page; null when exhausted."}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/videos/{videoId}":{"get":{"x-resource-group":"ads","operationId":"getAdVideoStatus","tags":["Ad Creatives"],"x-platforms":["meta"],"summary":"Get ad video processing status","description":"Checks whether an uploaded Meta ad video has finished processing and is ready to use in an ad.\n\nReads a video's processing state live from Meta (`GET /{video-id}?fields=status`).\nPoll this after `POST /v1/ads/videos` with `async: true` until `status` is `ready`;\nthe video is only usable as `video.id` on the create endpoints from then on.\n\n`status` is normalised: `ready`, `error` (Meta's `error` or `expired`), and\n`processing` for every other Meta state. `platformStatus` carries Meta's raw\n`video_status` and `processingProgress` Meta's 0-100 percentage when it reports one.\nPolling every 5 to 10 seconds is plenty.","security":[{"bearerAuth":[]}],"parameters":[{"name":"videoId","in":"path","required":true,"schema":{"type":"string"},"description":"Meta ad video id (numeric)."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"Meta ad account id (act_<n>) the video was uploaded to."}],"responses":{"200":{"description":"Processing status","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"video":{"type":"object","required":["id","status","platformStatus","processingProgress","error","thumbnailUrl"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["processing","ready","error"]},"platformStatus":{"type":["string","null"],"description":"Meta's raw status.video_status, forwarded verbatim."},"processingProgress":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Meta's processing percentage when reported."},"error":{"type":["string","null"],"description":"Meta's processing error when status is error."},"thumbnailUrl":{"type":["string","null"],"description":"Meta's auto-generated poster once ready, when Meta produced one."}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}},"delete":{"x-resource-group":"ads","operationId":"deleteAdVideo","tags":["Ad Creatives"],"x-platforms":["meta"],"summary":"Delete an ad video","description":"Removes a video from a Meta ad account's video library.\n\nMeta's canonical `DELETE /{video_id}` fails with code 10 / subcode 1363055 for videos uploaded via `/act_X/advideos`, even with `ads_management`.\n\nThis endpoint uses the working account-scoped shape `DELETE /act_X/advideos?video_id=<id>` and returns Meta's `{success: true}` verbatim.\n\nDeleting a video that lives in a different ad account, or that Meta has already removed, returns Meta's error verbatim as a 4xx.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"videoId","in":"path","required":true,"schema":{"type":"string"},"description":"Meta ad video id (numeric)."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"Meta ad account id (act_<n>) that owns the video."}],"responses":{"200":{"description":"Video deleted","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"videoId":{"type":"string"},"success":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only supported on Meta (facebook/instagram)"}}}},"/v1/ads/interests":{"get":{"x-resource-group":"ads","operationId":"searchAdInterests","deprecated":true,"tags":["Ad Targeting"],"x-platforms":["meta"],"summary":"Search targeting interests","description":"Deprecated alias for `GET /v1/ads/targeting/search?dimension=interest`. Kept for\nbackward compatibility, it returns the legacy `{ interests: [...] }` shape rather\nthan the normalized `{ results: [...] }`. New integrations should use\n`GET /v1/ads/targeting/search` with `dimension=interest`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Account ID"}],"responses":{"200":{"description":"Matching interests","content":{"application/json":{"schema":{"type":"object","properties":{"interests":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required: legacy plans need the Ads add-on, and usage-based plans include it by default.","description":"Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/ads/targeting/search":{"get":{"x-resource-group":"ads","operationId":"searchAdTargeting","tags":["Ad Targeting"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","reddit"],"summary":"Search targeting options","description":"Finds targeting options by name, such as locations, interests or behaviors, and returns the ids to use in ad targeting.\n\nIt resolves a human-readable query into the platform's opaque targeting ids used in the `TargetingSpec`: the `countries`/`regions`/`cities`/`zips`/`metros` geo keys and the `interests`/`behaviors` entity ids. Those ids are used on `POST /v1/ads/create`, `POST /v1/ads/targeting/reach-estimate`, and `saved_targeting` audiences.\n\n### Dimensions\n\nThe `dimension` param selects what is searched:\n\n- `geo`: locations, further scoped by `geoType`\n- `interest`\n- `interestSuggestion`: Meta only. Interests related to the interest names in `q`, from Meta's interest suggestions (details below)\n- `behavior`: Meta, TikTok and LinkedIn, matched by name; ids feed `TargetingSpec.behaviors` (details below)\n- `interestKeyword`: TikTok only. The \"Additional interests\" of TikTok Ads Manager (e.g. `folk` returns `Folk Music`), from TikTok's keyword recommendations for the seed `q` (details below)\n- `hashtag`: TikTok only. Hashtags recommended for the seed `q`, to target people who viewed videos with them (details below)\n- `income`: the household-income tiers the platform can target (Meta, TikTok, Google) (details below)\n- `language`: Google-only\n- `workPosition`, `workEmployer`, `workIndustry`: the Meta-only work demographics, whose ids feed `TargetingSpec.workPositions`/`workEmployers`/`workIndustries`\n- `industry`, `jobFunction`, `seniority`, `companySize`, `skill`: the LinkedIn-only B2B facets, whose URNs feed `TargetingSpec.industries`/`jobFunctions`/`seniorities`/`companySizes`/`skills`\n- `community`: Reddit only. Subreddits matching `q`. The id is the subreddit name for `TargetingSpec.communities` / `excludedCommunities`, `platformId` is Reddit's own id, and `audienceSize` its subscriber count when Reddit reports it\n- `conversationKeyword`: Reddit only. Reddit's keyword suggestions for the seed `q`. The id is the keyword for `TargetingSpec.conversationKeywords` / `excludedConversationKeywords`\n\nAvailability of each dimension varies by platform. A dimension a platform cannot search returns a 400 naming `dimension`. It never falls back to another dimension, and every result's `type` is the requested dimension (or the geo level for `geo`).\n\nResults are normalized across platforms into a single shape, so the same client code consumes Meta, TikTok, LinkedIn, X, Pinterest, Google and Reddit results.\n\n### `interestSuggestion` (Meta)\n\n`q` lists interest names, case sensitive, names and not ids, in one of two forms:\n\n- Comma-separated: `NBA,Michael Jordan`\n- For names that contain a comma, a JSON array of strings (`[\"Earth, Wind & Fire\",\"Yoga\"]`, URL-encoded). A `q` starting with `[` is always read as JSON.\n\nA `q` with no name or malformed JSON returns 400 naming `q`.\n\nMeta also suggests behaviors and demographics. Zernio keeps only interests, so every id goes in `TargetingSpec.interests`, like `interest` results. Zernio classifies them with a Meta call pinned to `en_US` (ids whose `path` starts with `Interests`).\n\nWithout `locale` results are in English. With another `locale`, a second call in that locale returns the same interests with localized names and `path`.\n\nZernio asks Meta for three times `limit` (at most 100) before filtering, so fewer than `limit` results can come back. Meta weights the first name heavily: a multi-name `q` mostly returns suggestions for the first one.\n\n### `behavior`\n\n- Meta: its fixed behaviors catalog (e.g. `Small business owners`, `Frequent Travelers`).\n- TikTok: video and creator interaction categories (e.g. `Software & Apps`), with ids like `video:1913101` or `creator:24001` and `path` starting with `Video interactions` or `Creator interactions`. Hashtags are their own `hashtag` dimension.\n- LinkedIn: member behaviors (e.g. `Frequent Travelers`, `Job Seekers`, `Recently Promoted`), ids like `urn:li:memberBehavior:9`.\n- Google has no separate behavior catalog: its in-market and affinity segments come back from `interest`.\n- X removed behavior targeting from its Ads API.\n\n### `interestKeyword` and `hashtag` (TikTok)\n\n- `interestKeyword` ids look like `keyword:123456` and go in `TargetingSpec.interests`, next to interest categories. Only keywords TikTok lets an ad group target come back (`status` `EFFECTIVE`). TikTok returns no audience size.\n- `hashtag` ids look like `hashtag:123456` and go in `TargetingSpec.behaviors`. Only hashtags TikTok reports `ONLINE` come back.\n- For `hashtag`, spaces in `q` are removed first, because TikTok recommends no hashtags for a multi-word seed (`acoustic guitar` searches `acousticguitar`).\n\nFor both, a `q` made only of prefixed ids (`keyword:101,keyword:102` or `hashtag:201`) looks those ids up instead of searching. Unavailable ones are included with their `status` (`INEFFECTIVE` or `OFFLINE`), so ids read back from an ad group (`interest_keyword_ids`, `actions` in `nativeSettings`) resolve to names.\n\nAn `interestKeyword` lookup takes at most 50 ids (more returns 400 naming `q`).\n\n### `income`\n\nThe id is the normalized tier (`top_5`, `top_10`, `top_10_25`, `top_25_50`) to pass as `TargetingSpec.incomeTier`, never a platform segment id.\n\n- Meta: tiers are US-only ZIP-code percentiles (label and `audienceSize` come live from Meta).\n- TikTok: expresses all four.\n- Google: only `top_10`.\n\n`q` is matched against the label, so `top` or `income` lists every tier.\n\n### TikTok `interest`\n\nTikTok `interest` searches TikTok's interest category catalog (about 700 categories over four levels, `path` holds the parent categories), matched by name in Zernio. The ids are what `TargetingSpec.interests` sends to TikTok as `interest_category_ids`.\n\n### Meta `workIndustry` and Google `language`\n\nWork industries are a fixed ~30-entry Meta catalog with no server-side query, so `workIndustry` matching, ranking and `limit` happen in Zernio.\n\n`language` is likewise a fixed, checked-in table of Google's targetable `language_constant` rows (id, ISO code, name). It is matched by name or code, capped at 20, with no network call. Its ids feed `TargetingSpec.languages`.\n\n### Geo queries\n\nFor geo queries, `q` should contain only the locality name (e.g. `\"Amsterdam\"`, not `\"Amsterdam, NL\"`). Use `countryCode` to disambiguate.\n\n### TikTok geo\n\nTikTok geo searches return every matching level in one list (`type` is `country`, `region`, `city`, `district`, or `metro` for DMA areas), and `geoType` is not applied.\n\n`path` starts with the country code, then the parent regions from the top down, so same-name places can be told apart. In the US the regions are the state, then the county: Austin, Texas reads `[\"US\", \"Texas\", \"Travis\"]`.\n\nResults are scoped to the advertiser's targetable markets (pass `adAccountId` when the connection holds several advertisers). A two-letter `q` also matches a country by ISO code (`q=GB` returns the United Kingdom first).\n\nA `country` result's id is its ISO 3166-1 alpha-2 code, for `targeting.countries`. Every other id is TikTok's numeric location id, usable in `regions`/`cities`/`metros` keys on `POST /v1/ads/create`.\n\n### LinkedIn geo\n\nLinkedIn geo searches also return every matching level in one list. Neither `geoType` nor `countryCode` is applied: LinkedIn's typeahead only returns a name and a URN per result, with no level or country field to filter on.\n\n- A result whose URN is a country Zernio holds a code for has `type: country` and its ISO 3166-1 alpha-2 code as the id, for `targeting.countries`.\n- Every other result has `type: region` and keeps its `urn:li:geo:*` URN as the id, usable as a `regions[].key` on `POST /v1/ads/create`, `POST /v1/ads/boost` and `POST /v1/ads/targeting/reach-estimate`.\n\nLinkedIn puts countries and regions in the same `locations` facet, so both target the same way.\n\n### LinkedIn B2B\n\nLinkedIn B2B searches (`industry`, `jobFunction`, `seniority`, `companySize`, `skill`) return the full URN to pass straight back, so no URN id fragment has to be assembled by hand:\n\n- `urn:li:industry:4`\n- `urn:li:function:8`\n- `urn:li:seniority:6`\n- `urn:li:staffCountRange:(51,200)`\n- `urn:li:skill:1346`\n\nOnly `industry` and `skill` are server-side name searches (LinkedIn's typeahead finder).\n\nLinkedIn exposes no typeahead for job functions, seniorities and company sizes. Zernio fetches each whole table (26, 10 and 9 entries), caches it, and does the matching, ranking and `limit` cutoff itself. Those three never carry `audienceSize`.\n\n`countryCode` and `geoType` are not applied to any of the four.\n\n### Google geo\n\nGoogle geo searches resolve against Google's geoTargetConstants and return every matching level in one list.\n\n`geoType` is not applied (Google's `target_type` is an open taxonomy that does not map one-to-one onto the `geoType` enum). Filter client-side on the returned `type` (`country`, `region`, `city`, `zip`, `metro`, or the lowercased Google target type for rarer levels). `countryCode` scopes the search to one country.\n\nA `country` result's id is its ISO 3166-1 alpha-2 code, for `targeting.countries`. Every other id is Google's numeric criterion id, usable as a `regions`/`cities`/`zips`/`metros` `key` on `POST /v1/ads/create`.\n\nGoogle city radius is not supported (pass a `customLocations` lat/lng pin for a radius). Country targeting also accepts plain ISO codes via `countries` with no search call.\n\n### Pinterest\n\nPinterest resolves against three whole-catalog endpoints (interests, locations, regions) with no server-side query or pagination. Matching, ranking and the `limit` cutoff all happen in Zernio.\n\nThe catalog is independent of any ad account and results never carry `audienceSize`. Names come back localized to the connected Pinterest account's language (there is no way to force a locale), so match against whatever language that account returns.\n\n`geoType` routes to a different Pinterest catalog:\n\n- `country` and `metro_area` read the locations catalog (`type` is `country` or `metro`)\n- `region` reads the regions catalog (`type` is `region`, its id a `regions[].key` on `POST /v1/ads/create`)\n- `all` and the default `city` merge both catalogs with honest per-entry `type`s, since Pinterest has no city-level catalog and `city` is an alias for `all`, not a literal city search\n- `zip`, `subcity`, `neighborhood`, `place` and `geo_market` return a 400: Pinterest exposes no postal-code catalog, pass postal codes directly as `targeting.zips: [{ key }]` on `POST /v1/ads/create`\n\n### Reddit\n\nReddit (`redditads` connection) searches `geo`, `interest`, `community` and `conversationKeyword`. Any other dimension returns 400.\n\nIts geo search honours these `geoType` values (other values return 400):\n\n- `city`: the default, a server-side city search\n- `zip`: `q` is the postal code\n- `country`, `region` and `metro_area`: matched in Zernio against Reddit's geolocation catalog\n- `all`\n\n`countryCode` scopes every geo search. Each result's id is Reddit's geolocation id, usable as a `regions`/`metros`/`cities`/`zips` `key` (country ids go in `countries`).\n\n`interest` matches Reddit's interest catalog in Zernio, with the category as `path`.\n\n### Meta language\n\nMeta matches `q` against names in one language and returns names and `path` in that language. Pass `locale` (e.g. `pl_PL`) to choose it.\n\nWithout `locale`:\n\n- The `behavior` and `workIndustry` catalogs and `interestSuggestion` are in `en_US`.\n- `interest`, `geo`, `workPosition` and `workEmployer` follow the language of the Facebook user who connected the account (so a Russian-language Facebook user gets Russian paths, and Polish names need `locale=pl_PL`).\n\nA non-English `behavior` or `workIndustry` query without `locale` never matches, so pass the locale of the names you search.\n\nMeta's `interest` search matches its own interest names and has no fuzzy or synonym mode. A phrase Meta does not use as an interest name (e.g. `dental implants`) can return nothing while a shorter word (`dentistry`) does.\n\nIf Meta returns an empty `behavior`, `workIndustry` or `income` catalog, the request fails with a 502 `platform_api_error` instead of an empty `results` list.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Account ID (a connected account on the target ad platform)."},{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query. For geo, the locality name only (no region/country suffix). For `interestSuggestion`, the interest names: comma-separated, or a JSON array of strings when a name contains a comma (a `q` starting with `[` is read as JSON)."},{"name":"dimension","in":"query","required":false,"schema":{"type":"string","enum":["geo","interest","interestSuggestion","interestKeyword","behavior","hashtag","income","language","workPosition","workEmployer","workIndustry","industry","jobFunction","seniority","companySize","skill","community","conversationKeyword"],"default":"interest"},"description":"What to search. Defaults to `interest` for backward compatibility with the deprecated /v1/ads/interests alias.\n\n- `geo`: resolves locations (scope further with `geoType`).\n- `interest`/`behavior`: resolve audience entities (`behavior` on Meta, TikTok and LinkedIn).\n- `interestSuggestion`: suggests interests related to the names in `q` (Meta only).\n- `interestKeyword`/`hashtag`: resolve TikTok additional interests and hashtags (TikTok only).\n- `income`: resolves the normalized income tiers.\n- `language`: resolves Google's targetable language_constant table (Google only).\n- `workPosition`/`workEmployer`/`workIndustry`: resolve Meta work demographics.\n- `industry`/`jobFunction`/`seniority`/`companySize`/`skill`: resolve LinkedIn B2B facets (LinkedIn only)."},{"name":"geoType","in":"query","required":false,"schema":{"type":"string","enum":["all","country","country_group","region","city","subcity","neighborhood","place","zip","metro_area","geo_market"],"default":"city"},"description":"Only used when `dimension=geo`. The kind of location to resolve. `all` searches every type in one relevance-ranked call. Defaults to `city`."},{"name":"countryCode","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2},"description":"ISO 3166-1 alpha-2 country code (e.g. NL) to scope a geo search."},{"name":"adAccountId","in":"query","required":false,"schema":{"type":"string"},"description":"TikTok only: the advertiser to search as, when the connection holds several. Each TikTok advertiser has its own targetable regions and catalogs. Defaults to the connection's first advertiser; an advertiser the connection does not hold returns 400."},{"name":"locale","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-z]{2,3}_[A-Z]{2}$","examples":["pl_PL"]},"description":"Meta only (ignored on other platforms). The language Meta matches `q` against and names results and `path` in, as language_TERRITORY (e.g. `pl_PL`, `en_US`).\n\nApplies to `geo`, `interest`, `interestSuggestion`, `behavior`, `workPosition`, `workEmployer` and `workIndustry`.\n\n**Without it:** `behavior`, `workIndustry` and `interestSuggestion` use `en_US`; other searches use the language of the Facebook user who connected the account. `income` always uses `en_US`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum results to return."}],"responses":{"200":{"description":"Matching targeting options (normalized)","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","required":["id","name","type"],"properties":{"id":{"type":"string","description":"The platform's opaque id. Use as a geo `key` (regions/cities/zips/metros) or an entity `id` (interests/behaviors) in TargetingSpec. A `country` result is the exception on every platform: its id is the ISO 3166-1 alpha-2 code, which is what `targeting.countries` takes."},"name":{"type":"string","description":"Human-readable label."},"type":{"type":"string","description":"What the result is. Equals the requested dimension (interest, interestSuggestion, interestKeyword, behavior, hashtag, income, language, workPosition, workEmployer, workIndustry, industry, jobFunction, seniority, companySize, skill, community, conversationKeyword), or the location level for geo (country, region, city, zip, metro, ...)."},"path":{"type":"array","items":{"type":"string"},"description":"Optional breadcrumb of parent labels (e.g. ['United States', 'California', 'Los Angeles']). Disambiguates same-named results."},"audienceSize":{"type":["integer","null"],"description":"Optional estimated reachable users for this option, when the platform returns it."},"status":{"type":"string","description":"TikTok `interestKeyword` and `hashtag` results only: TikTok's availability status. `EFFECTIVE` / `INEFFECTIVE` for additional interests, `ONLINE` / `OFFLINE` for hashtags. Only `EFFECTIVE` and `ONLINE` ids can be targeted."},"countryCode":{"type":"string","description":"ISO-3166 alpha-2 of the country a sub-country geo result (city, region, zip, metro) belongs to, when the platform reports it (Meta does). Useful to know whether a location falls under the EU DSA disclosure rules before creating the ad."},"platformId":{"type":"string","description":"The platform's own id for the result.\n\n- Reddit `community` results: Reddit's own subreddit id (the `id` is the name).\n- `country` results: the platform's own id for the country, which `id` replaced with the ISO code. TikTok's native location_id (a GeoNames id such as 2635167 for GB), Meta's country key, Google's geo target constant id, X's targeting value, LinkedIn's geo URN.\n- Other results: absent.\n\nUse it to match a country against what the platform reports back, e.g. `location_ids` in a TikTok `nativeSettings` read."}}}}}}}}},"400":{"description":"Missing or invalid query parameters"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required: legacy plans need the Ads add-on, and usage-based plans include it by default.","description":"Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/ads/targeting/browse":{"get":{"x-resource-group":"ads","operationId":"browseAdTargeting","tags":["Ad Targeting"],"x-platforms":["meta"],"summary":"Browse targeting categories","description":"Shows Meta's full tree of detailed targeting categories for an ad account, so you can browse options without a keyword.\n\nIt returns the whole Meta detailed-targeting category tree of one ad account (Meta's `GET /act_{ad_account_id}/targetingbrowse`), as one flat list you can render as a tree. Use it to show what can be targeted without a keyword; use `GET /v1/ads/targeting/search` to find an entry by name.\n\n### Node kinds\n\nEvery node is one of two kinds.\n\n**Selectable entity** (`selectable: true`): an interest, behavior or demographic Meta gives an id. `id` plus `type` is what a targeting spec takes.\n\n- `interests`, `behaviors` and `industries` ids go in `TargetingSpec.interests`, `behaviors` and `workIndustries` on `POST /v1/ads/create`.\n- Every other type goes in `rawTargeting.flexible_spec` under its `type` as the key.\n- `life_events`, `family_statuses` and `income` take objects (`{ \"flexible_spec\": [{ \"life_events\": [{ \"id\": \"6017476616183\" }] }] }`).\n- `education_statuses` and `relationship_statuses` take the bare number (`{ \"flexible_spec\": [{ \"education_statuses\": [3] }] }`): Meta answers an object there with a 500.\n\n**Organizational node** (`selectable: false`, `id: null`): a category such as `Demographics > Financial > Income` that only groups other nodes and cannot be targeted.\n\nA few organizational nodes carry a `type` and have no children (`Schools`, `Employers`, `Job titles`, `Fields of study`, `Undergrad years`). Those are open-ended categories Meta only exposes through search (`dimension=workEmployer` / `workPosition` on the search endpoint).\n\n### Node ids\n\n- `nodeId` identifies a node within this response.\n- `parentNodeId` points at its parent (`null` for the three roots `Demographics`, `Interests`, `Behaviors`).\n- A selectable node's `nodeId` is `{type}:{id}`, because Meta reuses small ids across types (education status 3 and relationship status 3 are different entities).\n- An organizational node's `nodeId` is its full path joined with ` > `.\n\nLabels are kept exactly as Meta sends them, including stray leading or trailing spaces, because Meta has sibling nodes that differ only by whitespace.\n\nThe interests branch is Meta's curated browse list (a few hundred entries), not every interest Meta can target: search finds the long tail.\n\n### No pagination\n\nMeta returns the whole catalog in one response (about 770 nodes) and ignores `limit`, so there is no cursor. Narrow it with `type`, `parentNodeId` and `selectable` instead; they are applied by Zernio.\n\nThe catalog is cached for an hour per ad account and connection.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"A connected Meta account (metaads, facebook or instagram). Any other ad platform returns 501 platform_not_supported."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string","pattern":"^act_\\d+$"},"description":"The Meta ad account to browse as, in the form \"act_<digits>\"."},{"name":"type","in":"query","required":false,"schema":{"type":"string"},"description":"Only the nodes of this Meta type (e.g. interests, behaviors, life_events, income), plus the organizational nodes leading to them. A type that is not in the catalog returns 400."},{"name":"parentNodeId","in":"query","required":false,"schema":{"type":"string"},"description":"Only the descendants (every depth) of this organizational node, e.g. `Demographics > Financial`. A nodeId that is not an organizational node of the catalog returns 400."},{"name":"selectable","in":"query","required":false,"schema":{"type":"boolean"},"description":"`true` for selectable entities only, `false` for organizational nodes only."}],"responses":{"200":{"description":"The category tree as a flat list, in Meta's order (parents before their children).","content":{"application/json":{"schema":{"type":"object","required":["adAccountId","nodes"],"properties":{"adAccountId":{"type":"string"},"nodes":{"type":"array","items":{"type":"object","required":["nodeId","parentNodeId","id","name","type","path","selectable"],"properties":{"nodeId":{"type":"string","description":"Identifies the node within this response. Not a Meta id: never put it in a targeting spec."},"parentNodeId":{"type":["string","null"],"description":"nodeId of the parent organizational node, null for a root."},"id":{"type":["string","null"],"description":"Meta targeting id, null on organizational nodes."},"name":{"type":"string"},"type":{"type":["string","null"],"description":"Meta's targeting spec key (interests, behaviors, industries, life_events, education_statuses, relationship_statuses, family_statuses, income, ...). Null on most organizational nodes."},"path":{"type":"array","items":{"type":"string"},"description":"Labels of the ancestors, root first. Does not include the node itself."},"selectable":{"type":"boolean","description":"True when the node can be targeted (it has a Meta id)."},"description":{"type":"string","description":"Meta's description, when it has one."},"audienceSizeLowerBound":{"type":"integer","description":"Meta's estimated audience size, lower bound, when reported."},"audienceSizeUpperBound":{"type":"integer","description":"Meta's estimated audience size, upper bound, when reported."}}}}}},"example":{"adAccountId":"act_1234567890","nodes":[{"nodeId":"Demographics > Financial > Income","parentNodeId":"Demographics > Financial","id":null,"name":"Income","type":null,"path":["Demographics","Financial"],"selectable":false},{"nodeId":"income:6107813551783","parentNodeId":"Demographics > Financial > Income","id":"6107813551783","name":"Household income: top 10% of ZIP codes (US)","type":"income","path":["Demographics","Financial","Income"],"selectable":true,"description":"People who live in the top 10% of US ZIP codes by average household income based on publicly available information","audienceSizeLowerBound":31201895,"audienceSizeUpperBound":36693429}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix it, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"accountId is not a Meta connection (platform_not_supported)."}}}},"/v1/ads/library":{"get":{"x-resource-group":"ads","operationId":"searchAdLibrary","tags":["Ad Library"],"x-platforms":["meta","linkedin"],"summary":"Search the public Ad Library","description":"Searches Meta's or LinkedIn's public Ad Library to see what ads other advertisers run, for competitor and market research.\n\n### Which library is searched\n\n- Meta's Ad Library (`GET /ads_archive`) is searched with Zernio's own developer access, so `platform=meta` needs no connected account at all.\n- LinkedIn's Ad Library (`GET /rest/adLibrary`) runs on a connected `linkedin` / `linkedinads` account, passed as `accountId`.\n- Passing a Meta account as `accountId` also selects Meta.\n\nRows are returned in the platform's raw shape under `data`. `paging.after` is an opaque cursor on both (`null` when exhausted).\n\n**Meta coverage.** Political and social-issue ads are searchable worldwide. Every other ad is in the archive only if it was delivered to the EU or UK within the last year, so a US-only commercial advertiser is invisible.\n\nSpend, impressions and demographics are political-only fields and are left out of the default projection; request them via `fields`.\n\n**Meta rate limit.** Meta searches are capped at 30 requests per hour per team, because all customers share Zernio's Meta quota. Meta can also throttle that shared quota. Either way you get a `429` with `Retry-After`: wait that long before retrying.\n\n**LinkedIn coverage.** Ads served after June 1 2023, worldwide, kept for a year after their last impression. EU-delivered ads carry impression ranges and the disclosed targeting facets.\n\nPages are capped at 25 ads (`limit` > 25 is a 400). `after` is the next offset.\n\n### Which params apply\n\n- Both: `q`, `countries`, `limit`, `after`\n- Meta-only: `pageIds`, `adType`, `status`, `platforms`, `mediaType`, `languages`, `searchType`, `fields`, `since`, `until`\n- LinkedIn-only: `advertiser`\n\nPassing a param the account's platform does not support is a 400 naming the param.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"platform","in":"query","schema":{"type":"string","enum":["meta","linkedin"]},"description":"Which archive to search. `meta` needs no accountId. Required unless accountId is given."},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Zernio SocialAccount id. Required for LinkedIn (linkedin / linkedinads: its token searches). Optional for Meta, where any facebook / instagram / metaads account only selects the platform."},{"name":"q","in":"query","schema":{"type":"string","maxLength":100},"description":"Keyword search. Meta does not translate it, so write it in the ads' language. Required unless pageIds (Meta) or advertiser (LinkedIn) is given."},{"name":"pageIds","in":"query","schema":{"type":"string"},"description":"Meta only. Comma-separated Facebook Page ids (max 10) whose ads to list."},{"name":"advertiser","in":"query","schema":{"type":"string","maxLength":100},"description":"LinkedIn only. Advertiser (Page) name to search."},{"name":"countries","in":"query","schema":{"type":"string"},"description":"Comma-separated ISO 3166-1 alpha-2 codes the ads reached. Meta defaults to ALL (an explicit ALL is Meta-only); LinkedIn searches every market when omitted."},{"name":"adType","in":"query","schema":{"type":"string","enum":["ALL","POLITICAL_AND_ISSUE_ADS","HOUSING_ADS","EMPLOYMENT_ADS","FINANCIAL_PRODUCTS_AND_SERVICES_ADS"],"default":"ALL"},"description":"Meta only."},{"name":"status","in":"query","schema":{"type":"string","enum":["ACTIVE","INACTIVE","ALL"],"default":"ACTIVE"},"description":"Meta only. ACTIVE = eligible for delivery right now."},{"name":"platforms","in":"query","schema":{"type":"string"},"description":"Meta only. Comma-separated publisher platforms: FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER, WHATSAPP, OCULUS, THREADS, STREAMING_SERVICES."},{"name":"mediaType","in":"query","schema":{"type":"string","enum":["ALL","IMAGE","MEME","VIDEO","NONE"]},"description":"Meta only."},{"name":"languages","in":"query","schema":{"type":"string"},"description":"Meta only. Comma-separated ISO 639-1 codes of the ad text."},{"name":"since","in":"query","schema":{"type":"string","format":"date"},"description":"Meta only. Earliest delivery date (YYYY-MM-DD). LinkedIn's archive does not filter by date, so it is a 400 there: filter on details.adStatistics.firstImpressionAt / latestImpressionAt instead (EU-delivered ads only)."},{"name":"until","in":"query","schema":{"type":"string","format":"date"},"description":"Meta only. Latest delivery date (YYYY-MM-DD); a 400 on LinkedIn, see since."},{"name":"searchType","in":"query","schema":{"type":"string","enum":["KEYWORD_UNORDERED","KEYWORD_EXACT_PHRASE"],"default":"KEYWORD_UNORDERED"},"description":"Meta only. Whether q matches words in any order or as an exact phrase (comma-separate phrases to match all of them)."},{"name":"fields","in":"query","schema":{"type":"string","example":"id,page_name,ad_delivery_start_time,ad_creative_bodies"},"description":"Meta only. Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers, so a nested edge can be paged explicitly: without a .limit() modifier the expansion runs at the Meta default page size and the tail is dropped silently."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Rows per page. LinkedIn accepts at most 25."},{"name":"after","in":"query","schema":{"type":"string"},"description":"paging.after of the previous page."}],"responses":{"200":{"description":"Archived ads (raw platform shape)","content":{"application/json":{"schema":{"type":"object","required":["platform","data","paging"],"properties":{"platform":{"type":"string","enum":["meta","linkedin"]},"data":{"type":"array","items":{"type":"object","description":"One ad library entry, in the platform's shape.\n\n**Meta:** an ArchivedAd with:\n\n- id, page_id, page_name, ad_creation_time, ad_delivery_start_time, ad_delivery_stop_time.\n- ad_creative_bodies[], ad_creative_link_titles[], ad_creative_link_descriptions[], ad_creative_link_captions[].\n- ad_snapshot_url (access token stripped), ad_library_url (public Ad Library permalink), publisher_platforms[], languages[].\n- On EU/UK ads also: eu_total_reach, beneficiary_payers, target_ages, target_gender, target_locations, age_country_gender_reach_breakdown, total_reach_by_location.\n\n**LinkedIn:** { adUrl, isRestricted, details: { type, advertiser: { advertiserName, advertiserUrl, adPayer }, adStatistics: { firstImpressionAt, latestImpressionAt, totalImpressions: { from, to }, impressionsDistributionByCountry[] }, adTargeting: [{ facetName, includedSegments[], excludedSegments[] }] } }\n\nadStatistics and adTargeting are present only on EU-delivered ads.\n"}},"paging":{"type":"object","properties":{"after":{"type":["string","null"],"description":"Cursor for the next page; null when exhausted."},"total":{"type":"integer","description":"LinkedIn only. Total matching ads."}}}}},"examples":{"meta":{"summary":"Meta, an EU-delivered ad","value":{"platform":"meta","data":[{"id":"1234567890","page_id":"811889972008357","page_name":"Zernio","ad_creation_time":"2026-08-02","ad_delivery_start_time":"2026-08-03","ad_creative_bodies":["Schedule posts and run ads from one API."],"ad_creative_link_titles":["Zernio for developers"],"ad_snapshot_url":"https://www.facebook.com/ads/archive/render_ad/?id=1234567890","ad_library_url":"https://www.facebook.com/ads/library/?id=1234567890","publisher_platforms":["facebook","instagram"],"languages":["en"],"eu_total_reach":18400,"target_ages":["25","54"],"target_gender":"All"}],"paging":{"after":"QVFIUm..."}}},"linkedin":{"summary":"LinkedIn, an EU-delivered ad","value":{"platform":"linkedin","data":[{"isRestricted":false,"adUrl":"https://www.linkedin.com/ad-library/detail/1521996423","details":{"type":"SPONSORED_STATUS_UPDATE","advertiser":{"advertiserName":"CEE Microsoft Dynamics Partners","advertiserUrl":"https://www.linkedin.com/company/71491884","adPayer":"UAB Companial"},"adStatistics":{"firstImpressionAt":1788623666998,"latestImpressionAt":1788780782520,"totalImpressions":{"from":5000,"to":10000},"impressionsDistributionByCountry":[]},"adTargeting":[{"facetName":"Language","includedSegments":["polski"],"excludedSegments":[]},{"facetName":"Location","includedSegments":["Polska"],"excludedSegments":[]}]}}],"paging":{"after":"25","total":27147}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or no payment method is on file: enable Ads access or add a card.","description":"Ads access required (legacy plans need the Ads add-on; included on usage-based plans), or `payment_required`: the billing owner has no payment method on file and no legacy paid plan. Searches are free; the card keeps the shared archive quota for real accounts."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"Only supported on Meta and LinkedIn accounts"},"503":{"description":"Meta's Ad Library is unavailable on Zernio's side (`PLATFORM_DISABLED`); LinkedIn searches are unaffected."}}}},"/v1/ads/targeting/reach-estimate":{"post":{"x-resource-group":"ads","operationId":"estimateAdReach","tags":["Ad Targeting"],"x-platforms":["meta","linkedin","pinterest","x"],"summary":"Estimate audience reach","description":"Estimates how many people a targeting setup would reach before you create a campaign.\n\nReturns a normalized pre-flight audience-size estimate for a targeting spec,\nbefore any campaign is created. Backed by each platform's native reach API\n(Meta `delivery_estimate`, LinkedIn `audienceCounts`, X `audience_summary`,\nPinterest `audience_sizing`).\n\nPlatforms without a usable pre-flight reach API (Google Search/Display, TikTok)\nreturn `available: false` with no bounds, so clients can hide or grey out the\nestimate rather than treat the absence as an error.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","adAccountId"],"properties":{"accountId":{"type":"string","description":"Zernio account ID on the target ad platform (the estimate runs against its platform)."},"adAccountId":{"type":"string","description":"Required. The platform ad-account ID the reach call runs against (Meta act_..., LinkedIn numeric sponsoredAccount ID, Pinterest ad-account ID, X account ID) - every backing reach API is scoped to one ad account. Get it from GET /v1/ads/accounts."},"spec":{"allOf":[{"$ref":"#/components/schemas/TargetingSpec"}],"description":"The targeting spec to estimate. Same shape used by POST /v1/ads/create. Required unless `rawTargeting` is sent; with `rawTargeting` it can be omitted or minimal."},"rawTargeting":{"type":"object","additionalProperties":true,"description":"Meta only. A Meta-native targeting spec (snake_case: `geo_locations`, `age_min`, `flexible_spec`, `excluded_custom_audiences`, `user_os`, ...), the same field `POST /v1/ads/create` accepts, so the estimate covers the exact audience the ad set will use. Sending it for an account on another platform returns 400 naming `rawTargeting`.\n\nFor layered targeting, send `flexible_spec` here: entries AND together, ids inside one entry OR.\n\n**Merge rules** (same as `POST /v1/ads/create`):\n\n- rawTargeting is the BASE layer; `spec`, converted to Meta's wire shape, is merged on top key by key, with `spec` winning on collision.\n- The merge goes one level deep inside `geo_locations` and `excluded_geo_locations` (spec sub-keys win, raw-only sub-keys such as `location_types` survive).\n- Array values (`flexible_spec`, ...) are replaced as a whole key when `spec` builds them, never element-merged, so `spec.interests` or `spec.behaviors` replace a raw `flexible_spec`.\n\nThe result is sent to Meta `delivery_estimate` as `targeting_spec`.\n"},"optimizationGoal":{"type":"string","description":"Optional. The optimization goal the estimate should assume (platform's\nown vocabulary, e.g. Meta `REACH`, `LINK_CLICKS`, `OFFSITE_CONVERSIONS`).\nSome platforms vary the estimate by goal; omit to use the platform default.\n"}}}}}},"responses":{"200":{"description":"Normalized reach estimate","content":{"application/json":{"schema":{"type":"object","required":["available"],"properties":{"available":{"type":"boolean","description":"Whether a pre-flight estimate is available on this platform. False for Google and TikTok."},"lower":{"type":["integer","null"],"description":"Lower bound of the estimated reachable audience. Present only when available."},"upper":{"type":["integer","null"],"description":"Upper bound of the estimated reachable audience. Present only when available."},"daily":{"type":["integer","null"],"description":"Optional estimated daily reach/results at the given budget, when the platform returns it."},"active":{"type":["integer","null"],"description":"LinkedIn only. LinkedIn's `audienceCounts.active`, verbatim: the active subset of the same audience `lower`/`upper` carry as its `total`. Absent when LinkedIn does not report it; `0` is a real answer, not a missing one."},"currency":{"type":["string","null"],"description":"Currency of any monetary fields in the estimate, when applicable."},"estimateReady":{"type":["boolean","null"],"description":"Meta only. False when Meta is still computing the estimate (the audience is too new); retry shortly."}}}}}},"400":{"description":"Missing required fields or a targeting field the platform cannot honour"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required: legacy plans need the Ads add-on, and usage-based plans include it by default.","description":"Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/ads/targeting/bid-pricing":{"post":{"x-resource-group":"ads","operationId":"getLinkedInBidPricing","tags":["Ad Targeting"],"x-platforms":["linkedin"],"summary":"Suggested bid and budget bounds","description":"LinkedIn-only. Returns the suggested bid and bid limits for a targeting\nspec, plus the daily-budget bounds LinkedIn will accept. Use it before\ncreating a campaign to pick a bid inside the allowed range and warn the\nuser if their daily budget is below the minimum. Wraps LinkedIn's\n`adBudgetPricing` finder.\n\nNon-LinkedIn accounts return `available: false` so clients can hide the\npricing UI without treating it as a failure.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","adAccountId","spec"],"properties":{"accountId":{"type":"string","description":"Zernio account ID (LinkedIn)."},"adAccountId":{"type":"string","description":"LinkedIn ad account ID (numeric)."},"spec":{"allOf":[{"$ref":"#/components/schemas/TargetingSpec"}],"description":"Same targeting spec used by POST /v1/ads/create."},"campaignType":{"type":"string","enum":["TEXT_AD","SPONSORED_UPDATES","SPONSORED_INMAILS"],"description":"Defaults to SPONSORED_UPDATES."},"bidType":{"type":"string","enum":["CPM","CPC","CPV"],"description":"Defaults to CPM."},"matchType":{"type":"string","enum":["EXACT","AUDIENCE_EXPANDED"],"description":"Defaults to EXACT."},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217, defaults to USD."},"objectiveType":{"type":"string","description":"LinkedIn objectiveType, e.g. WEBSITE_VISIT, LEAD_GENERATION, VIDEO_VIEW."},"optimizationTargetType":{"type":"string","description":"LinkedIn optimizationTargetType, e.g. MAX_CLICK, MAX_IMPRESSION."},"dailyBudget":{"type":"number","description":"Optional daily budget in whole account-currency units. LinkedIn refines the suggested bid to this budget."}}}}}},"responses":{"200":{"description":"Pricing insights","content":{"application/json":{"schema":{"type":"object","required":["available"],"properties":{"available":{"type":"boolean"},"pricing":{"type":["object","null"],"description":"LinkedIn's adBudgetPricing element. Null when LinkedIn has no data for the combination.","properties":{"bidLimits":{"type":"object","properties":{"min":{"$ref":"#/components/schemas/MoneyAmount"},"max":{"$ref":"#/components/schemas/MoneyAmount"}}},"suggestedBid":{"type":"object","properties":{"min":{"$ref":"#/components/schemas/MoneyAmount"},"default":{"$ref":"#/components/schemas/MoneyAmount"},"max":{"$ref":"#/components/schemas/MoneyAmount"}}},"dailyBudgetLimits":{"type":"object","properties":{"min":{"$ref":"#/components/schemas/MoneyAmount"},"default":{"$ref":"#/components/schemas/MoneyAmount"},"max":{"$ref":"#/components/schemas/MoneyAmount"}}}}}}}}}},"400":{"description":"Invalid targeting or unsupported objective/optimization/bid combination."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads access required."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/ads/targeting/supply-forecast":{"post":{"x-resource-group":"ads","operationId":"getLinkedInSupplyForecast","tags":["Ad Targeting"],"x-platforms":["linkedin"],"summary":"Forecast ad delivery","description":"LinkedIn-only. Forecasted impressions, clicks, spend and ~20 other\nmetrics for a targeting spec over a time range. Wraps LinkedIn's\n`adSupplyForecasts` finder.\n\nEach returned series carries a `metricType` (IMPRESSION, CLICK, SPENDING,\nMAX_POTENTIAL_BUDGET, COST_PER_MILLION_IMPRESSIONS, ...) and a\n`granularity` (DAILY, SEVEN_DAY, THIRTY_DAY, CUSTOM). LinkedIn caps the\ndaily spending forecast at 1.2x the daily budget and returns 0 once the\ntotal budget is exhausted.\n\nNon-LinkedIn accounts return `available: false`.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","adAccountId","spec","timeRangeStart","timeRangeEnd"],"properties":{"accountId":{"type":"string"},"adAccountId":{"type":"string"},"spec":{"allOf":[{"$ref":"#/components/schemas/TargetingSpec"}]},"campaignType":{"type":"string","enum":["SPONSORED_UPDATES","SPONSORED_INMAILS","DYNAMIC"],"description":"Defaults to SPONSORED_UPDATES."},"timeRangeStart":{"type":"integer","description":"Unix ms. Must be in the future."},"timeRangeEnd":{"type":"integer","description":"Unix ms. Must be after start and within LinkedIn's max horizon."},"objectiveType":{"type":"string"},"optimizationTarget":{"type":"string","description":"When set, the forecast assumes auto-bidding. When unset, competingBid is required."},"dailyBudget":{"type":"number","description":"Either dailyBudget or totalBudget is required."},"totalBudget":{"type":"number"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217, defaults to USD."},"competingBid":{"type":"object","required":["bidType","amount"],"description":"Required for manual-bid forecasts (when optimizationTarget is not set).","properties":{"bidType":{"type":"string","enum":["CPM","CPC","CPV"]},"amount":{"type":"number"}}},"enableAudienceNetwork":{"type":"boolean","description":"Defaults to false. Required true for connectedTelevisionOnly."},"enableAudienceExpansion":{"type":"boolean","description":"Defaults to false."},"connectedTelevisionOnly":{"type":"boolean","description":"Defaults to false."}}}}}},"responses":{"200":{"description":"Forecast series","content":{"application/json":{"schema":{"type":"object","required":["available"],"properties":{"available":{"type":"boolean"},"forecast":{"type":"array","items":{"type":"object","properties":{"metricType":{"type":"string"},"granularity":{"type":"string","enum":["DAILY","SEVEN_DAY","THIRTY_DAY","CUSTOM"]},"timeSeries":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"integer"},"value":{"type":"number"},"adForecastRange":{"type":"object","properties":{"lowEnd":{"type":"number"},"highEnd":{"type":"number"}}}}}}}}}}}}}},"400":{"x-summary":"The targeting, budget or dates are invalid for the LinkedIn forecast: fix the request and resend.","description":"Invalid targeting, missing budget, or LinkedIn forecast validation error (e.g. END_DATE_MAX_HORIZON_FOR_FORECAST)."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads access required."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/ads/catalogs":{"get":{"x-resource-group":"ads","operationId":"listAdCatalogs","tags":["Product Catalogs"],"x-platforms":["meta"],"summary":"List Meta product catalogs","description":"Lists the Meta product catalogs a business portfolio owns or has been shared, for catalog and shopping ads.\n\n### Which business\n\nThe business comes from the first that applies:\n\n1. `businessId`\n2. the ad account's owner (`adAccountId`)\n3. the WhatsApp Business Account's owner, when `accountId` is a WhatsApp connection\n4. the only business the Meta login can see\n\n### Permission\n\nListing catalogs needs catalog_management on the Meta login. The permission is pending Meta App Review and is not requested on connect yet.\n\nSo most logins get the 403 below (Meta's code 100 \"This application has not been approved to use this api\"). Pass catalogAccountId naming a facebook, instagram or metaads connection whose Meta login already holds it.\n\nCreating a catalog_sales ad from a known product set ID does not need it (see promotedObject.productSetId on POST /v1/ads/create).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"A facebook, instagram, metaads or whatsapp account ID"},{"name":"catalogAccountId","in":"query","required":false,"schema":{"type":"string"},"description":"A facebook, instagram or metaads account whose Meta login carries catalog_management; its token is used instead of the account's own (needed for WhatsApp connections, whose token cannot manage catalogs)."},{"name":"adAccountId","in":"query","required":false,"schema":{"type":"string"},"description":"Meta ad account ID (act_...) whose owner business to list"},{"name":"businessId","in":"query","required":false,"schema":{"type":"string"},"description":"Meta business portfolio ID to list. When it is omitted and the Meta login can see several portfolios, the 400 carries `details.businesses` (id + name) so a client can offer the choice."}],"responses":{"200":{"description":"Catalogs","content":{"application/json":{"schema":{"type":"object","properties":{"businessId":{"type":"string"},"catalogs":{"type":"array","items":{"$ref":"#/components/schemas/MetaProductCatalog"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}},"post":{"x-resource-group":"ads","operationId":"createAdCatalog","tags":["Product Catalogs"],"x-platforms":["meta"],"summary":"Create a Meta product catalog","description":"Creates a Meta product catalog that can power catalog ads, Instagram and Facebook Shops, and a WhatsApp Business catalog.\n\nCreates a Meta Commerce catalog in the business portfolio (resolved like GET). The same catalog serves Advantage+ catalog ads, Instagram/Facebook Shops and the WhatsApp Business catalog: link it to a WhatsApp number with POST /v1/whatsapp/catalogs. Needs catalog_management on the Meta login.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","name"],"properties":{"accountId":{"type":"string","description":"A facebook, instagram, metaads or whatsapp account ID"},"catalogAccountId":{"type":"string","description":"Account whose Meta login token performs the call (see GET)"},"adAccountId":{"type":"string","description":"Ad account whose owner business creates the catalog"},"businessId":{"type":"string","description":"Business portfolio that owns the catalog"},"name":{"type":"string","maxLength":100},"vertical":{"type":"string","enum":["commerce","adoptable_pets","apps_and_software","articles_and_publications","destinations","flights","generic","home_listings","hotels","local_service_businesses","media_titles","offer_items","offline_commerce","services","transactable_items","vehicles","local_service_business"],"default":"commerce","description":"Meta catalog vertical. Use services for a professional services catalog (for example one linked to WhatsApp). local_service_business is a deprecated alias of local_service_businesses. The product endpoints under /v1/ads/catalogs/{catalogId}/products write commerce product items only."}}}}}},"responses":{"201":{"description":"Catalog created","content":{"application/json":{"schema":{"type":"object","properties":{"catalog":{"$ref":"#/components/schemas/MetaProductCatalog"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/ads/catalogs/{catalogId}":{"get":{"x-resource-group":"ads","operationId":"getAdCatalog","tags":["Product Catalogs"],"x-platforms":["meta"],"summary":"Get a product catalog","description":"Shows one Meta product catalog and its details.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/CatalogAccountId"},{"$ref":"#/components/parameters/CatalogTokenAccountId"}],"responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"type":"object","properties":{"catalog":{"$ref":"#/components/schemas/MetaProductCatalog"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"x-resource-group":"ads","operationId":"deleteAdCatalog","tags":["Product Catalogs"],"x-platforms":["meta"],"summary":"Delete a product catalog","description":"Deletes a Meta product catalog and all its products, removing it from any ads or WhatsApp numbers that use it.\n\nAds and WhatsApp numbers that use it lose their catalog.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/CatalogAccountId"},{"$ref":"#/components/parameters/CatalogTokenAccountId"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"catalogId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/ads/catalogs/{catalogId}/products":{"get":{"x-resource-group":"ads","operationId":"listAdCatalogProducts","tags":["Product Catalogs"],"x-platforms":["meta"],"summary":"List a catalog's products","description":"Lists the products in a Meta catalog, or looks one up by your own SKU.\n\nFilter by your own `retailerId` to look one up. `price` and `salePrice` come back formatted by Meta (for example \"€49.90\").\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/CatalogAccountId"},{"$ref":"#/components/parameters/CatalogTokenAccountId"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor from the previous page's `nextCursor`"},{"name":"retailerId","in":"query","required":false,"schema":{"type":"string"},"description":"Only the product with this retailer id (your SKU)"}],"responses":{"200":{"description":"Products","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/MetaCatalogProduct"}},"nextCursor":{"type":["string","null"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"x-resource-group":"ads","operationId":"createAdCatalogProduct","tags":["Product Catalogs"],"x-platforms":["meta"],"summary":"Add a product to a catalog","description":"Adds a single product to a Meta catalog, keyed by your own SKU for later lookups and updates.\n\n`retailerId` is your SKU and stays the handle for later lookups and batch updates. For many products at once use POST /v1/ads/catalogs/{catalogId}/products/batch. Needs catalog_management on the Meta login.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CatalogId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","product"],"properties":{"accountId":{"type":"string"},"catalogAccountId":{"type":"string"},"product":{"allOf":[{"$ref":"#/components/schemas/MetaCatalogProductInput"},{"type":"object","required":["retailerId","name","url","imageUrl","price","currency"]}]}}}}}},"responses":{"201":{"description":"Product created","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/MetaCatalogProduct"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/ads/catalogs/{catalogId}/products/batch":{"post":{"x-resource-group":"ads","operationId":"batchAdCatalogProducts","tags":["Product Catalogs"],"x-platforms":["meta"],"summary":"Create, update or delete products in bulk","description":"Creates, updates or deletes up to 5,000 catalog products in one request, processed in the background by Meta.\n\nUp to 5000 CREATE / UPDATE / DELETE requests keyed by `retailerId`, processed asynchronously by Meta. Returns handles; poll GET /v1/ads/catalogs/{catalogId}/batches/{handle} for the outcome and per-item errors. CREATE requests need name, url, imageUrl, price and currency.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CatalogId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","requests"],"properties":{"accountId":{"type":"string"},"catalogAccountId":{"type":"string"},"requests":{"type":"array","minItems":1,"maxItems":5000,"items":{"type":"object","required":["method","product"],"properties":{"method":{"type":"string","enum":["CREATE","UPDATE","DELETE"]},"product":{"allOf":[{"$ref":"#/components/schemas/MetaCatalogProductInput"},{"type":"object","required":["retailerId"]}]}}}}}}}}},"responses":{"202":{"description":"Accepted by Meta","content":{"application/json":{"schema":{"type":"object","properties":{"handles":{"type":"array","items":{"type":"string"}},"statusUrl":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/ads/catalogs/{catalogId}/batches/{handle}":{"get":{"x-resource-group":"ads","operationId":"getAdCatalogBatch","tags":["Product Catalogs"],"x-platforms":["meta"],"summary":"Get a bulk request's status","description":"Shows whether a bulk catalog product request has finished, with any per-product errors.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CatalogId"},{"name":"handle","in":"path","required":true,"schema":{"type":"string"},"description":"Handle returned by the batch call"},{"$ref":"#/components/parameters/CatalogAccountId"},{"$ref":"#/components/parameters/CatalogTokenAccountId"}],"responses":{"200":{"description":"Batch status","content":{"application/json":{"schema":{"type":"object","properties":{"batch":{"type":"object","properties":{"handle":{"type":"string"},"status":{"type":"string","description":"Meta's status, e.g. initial, in_progress, finished"},"errorsTotalCount":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"retailerId":{"type":["string","null"]},"message":{"type":"string"}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/ads/catalogs/{catalogId}/products/{productId}":{"get":{"x-resource-group":"ads","operationId":"getAdCatalogProduct","tags":["Product Catalogs"],"x-platforms":["meta"],"summary":"Get a product","description":"Shows one product from a Meta catalog.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/CatalogProductId"},{"$ref":"#/components/parameters/CatalogAccountId"},{"$ref":"#/components/parameters/CatalogTokenAccountId"}],"responses":{"200":{"description":"Product","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/MetaCatalogProduct"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"x-resource-group":"ads","operationId":"updateAdCatalogProduct","tags":["Product Catalogs"],"x-platforms":["meta"],"summary":"Update a product","description":"Changes some fields of a catalog product, such as its price or image, leaving the rest as they are.\n\n`retailerId` cannot change.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/CatalogProductId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","product"],"properties":{"accountId":{"type":"string"},"catalogAccountId":{"type":"string"},"product":{"$ref":"#/components/schemas/MetaCatalogProductInput"}}}}}},"responses":{"200":{"description":"Product updated","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/MetaCatalogProduct"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"x-resource-group":"ads","operationId":"deleteAdCatalogProduct","tags":["Product Catalogs"],"x-platforms":["meta"],"summary":"Delete a product","description":"Removes one product from a Meta catalog.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/CatalogProductId"},{"$ref":"#/components/parameters/CatalogAccountId"},{"$ref":"#/components/parameters/CatalogTokenAccountId"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"productId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/ads/catalogs/{catalogId}/feeds":{"get":{"x-resource-group":"ads","operationId":"listAdCatalogFeeds","tags":["Product Catalogs"],"x-platforms":["meta"],"summary":"List a catalog's product feeds","description":"Lists the product feeds that keep a Meta catalog filled from your product files.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/CatalogAccountId"},{"$ref":"#/components/parameters/CatalogTokenAccountId"}],"responses":{"200":{"description":"Feeds","content":{"application/json":{"schema":{"type":"object","properties":{"feeds":{"type":"array","items":{"$ref":"#/components/schemas/MetaProductFeed"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"x-resource-group":"ads","operationId":"createAdCatalogFeed","tags":["Product Catalogs"],"x-platforms":["meta"],"summary":"Create a product feed","description":"Creates a product feed that imports a CSV, TSV or XML product file into a Meta catalog, on a schedule or on demand.\n\nA feed pulls a CSV/TSV/XML product file from a URL. With `schedule` Meta fetches it on a cadence; without it, trigger fetches with POST /v1/ads/catalogs/{catalogId}/feeds/{feedId}/uploads.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CatalogId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","name"],"properties":{"accountId":{"type":"string"},"catalogAccountId":{"type":"string"},"name":{"type":"string","maxLength":100},"schedule":{"type":"object","required":["interval","url"],"properties":{"interval":{"type":"string","enum":["HOURLY","DAILY","WEEKLY"]},"url":{"type":"string","format":"uri"},"hour":{"type":"integer","minimum":0,"maximum":23},"dayOfWeek":{"type":"string","enum":["SUNDAY","MONDAY","TUESDAY","WEDNESDAY","THURSDAY","FRIDAY","SATURDAY"]}}}}}}}},"responses":{"201":{"description":"Feed created","content":{"application/json":{"schema":{"type":"object","properties":{"feed":{"$ref":"#/components/schemas/MetaProductFeed"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/ads/catalogs/{catalogId}/feeds/{feedId}/uploads":{"get":{"x-resource-group":"ads","operationId":"listAdCatalogFeedUploads","tags":["Product Catalogs"],"x-platforms":["meta"],"summary":"List a feed's uploads","description":"Lists a product feed's past file imports so you can check how each one went.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CatalogId"},{"name":"feedId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/CatalogAccountId"},{"$ref":"#/components/parameters/CatalogTokenAccountId"}],"responses":{"200":{"description":"Uploads, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"uploads":{"type":"array","items":{"$ref":"#/components/schemas/MetaFeedUpload"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"x-resource-group":"ads","operationId":"createAdCatalogFeedUpload","tags":["Product Catalogs"],"x-platforms":["meta"],"summary":"Fetch a feed file now","description":"Asks Meta to import a product file into a feed right away instead of waiting for its schedule.\n\nAsks Meta to fetch the product file at `url` into the feed. Processing is asynchronous: read the outcome with GET uploads.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CatalogId"},{"name":"feedId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","url"],"properties":{"accountId":{"type":"string"},"catalogAccountId":{"type":"string"},"url":{"type":"string","format":"uri"}}}}}},"responses":{"202":{"description":"Fetch started","content":{"application/json":{"schema":{"type":"object","properties":{"upload":{"type":"object","properties":{"id":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/ads/catalogs/{catalogId}/product-sets":{"get":{"x-resource-group":"ads","operationId":"listAdCatalogProductSets","tags":["Product Catalogs"],"x-platforms":["meta"],"summary":"List a catalog's product sets","description":"Lists a Meta catalog's product sets, the groups of products a catalog ad promotes.\n\nPass the chosen set id, not the parent catalog id, as `promotedObject.productSetId` on POST /v1/ads/create with `goal: catalog_sales`.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/CatalogAccountId"},{"$ref":"#/components/parameters/CatalogTokenAccountId"}],"responses":{"200":{"description":"Product sets","content":{"application/json":{"schema":{"type":"object","properties":{"productSets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"productCount":{"type":"integer"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"x-resource-group":"ads","operationId":"createAdCatalogProductSet","tags":["Product Catalogs"],"x-platforms":["meta"],"summary":"Create a product set","description":"Creates a product set, a filtered group of catalog products (by SKU, brand and so on) to promote in catalog ads.\n\nA product set is a filter over the catalog, e.g. `{\"retailer_id\": {\"is_any\": [\"sku-1\", \"sku-2\"]}}` or `{\"brand\": {\"i_contains\": \"acme\"}}` (Meta's product set filter syntax).\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CatalogId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","name","filter"],"properties":{"accountId":{"type":"string"},"catalogAccountId":{"type":"string"},"name":{"type":"string","maxLength":100},"filter":{"type":"object","additionalProperties":true,"description":"Meta product set filter"}}}}}},"responses":{"201":{"description":"Product set created","content":{"application/json":{"schema":{"type":"object","properties":{"productSet":{"$ref":"#/components/schemas/MetaProductSet"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/ads/catalogs/{catalogId}/product-sets/{productSetId}":{"put":{"x-resource-group":"ads","operationId":"updateAdCatalogProductSet","tags":["Product Catalogs"],"x-platforms":["meta"],"summary":"Update a product set","description":"Changes a product set's name or the filter that decides which products it includes.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CatalogId"},{"name":"productSetId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string"},"catalogAccountId":{"type":"string"},"name":{"type":"string","maxLength":100},"filter":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"Product set updated","content":{"application/json":{"schema":{"type":"object","properties":{"productSet":{"$ref":"#/components/schemas/MetaProductSet"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"x-resource-group":"ads","operationId":"deleteAdCatalogProductSet","tags":["Product Catalogs"],"x-platforms":["meta"],"summary":"Delete a product set","description":"Deletes a product set from a Meta catalog.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CatalogId"},{"name":"productSetId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/CatalogAccountId"},{"$ref":"#/components/parameters/CatalogTokenAccountId"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"productSetId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CatalogPermissionDenied"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/ads/audiences":{"get":{"x-resource-group":"ads","operationId":"listAdAudiences","tags":["Ad Audiences"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"List custom audiences","description":"Lists the custom audiences in an ad account so you can reuse them for targeting.\n\nSupports Meta, Google, TikTok, Pinterest, LinkedIn, X, and Reddit.\n\nOn Reddit, `size` is the lower bound of Reddit's matched-users range, and `status` is `too_small`\nwhile the list has matched fewer than 1,000 people.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Account ID"},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"Platform ad account ID"},{"name":"platform","in":"query","schema":{"type":"string","enum":["facebook","instagram","googleads","tiktok","tiktokads","pinterest","linkedin","linkedinads","twitter","xads","redditads"]}},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["customer_list","company_list","engagement","meta_engagement","website","website_retargeting","lookalike","saved_targeting"]},"description":"Filter to one audience type. `saved_targeting` returns stored TargetingSpec audiences; the other types return uploaded/derived audiences."}],"responses":{"200":{"description":"Audiences","content":{"application/json":{"schema":{"type":"object","properties":{"audiences":{"type":"array","items":{"type":"object","properties":{"id":{"type":["string","null"],"description":"The Zernio audience id. Pass this as audienceId on GET /v1/ads/audiences/{audienceId} and the companies/users upload endpoints. Null when the audience was not created through Zernio."},"accountId":{"type":"string","description":"Account the audience was created against. Returned for saved_targeting items."},"platformAudienceId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["customer_list","company_list","engagement","meta_engagement","tiktok_engagement","pinterest_engagement","website","website_retargeting","lookalike","saved_targeting","reddit_engagement","third_party","in_market"],"description":"`reddit_engagement`, `third_party` and `in_market` are listed from Reddit (engagement retargeting, and Reddit's own audiences) so they can be targeted. Zernio cannot create them."},"spec":{"anyOf":[{"$ref":"#/components/schemas/TargetingSpec"},{"type":"null"}],"description":"Present (and the only meaningful payload) when `type` is `saved_targeting`. Null for uploaded/derived audience types."},"platform":{"type":"string"},"size":{"type":"integer"},"summary":{"type":"string","description":"Who the audience contains, in one line (e.g. '1% lookalike of Customers in US' or 'All website visitors, last 30 days'). Meta only."},"status":{"type":"string"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is required: legacy plans need the Ads add-on, and usage-based plans include it by default.","description":"Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}},"post":{"x-resource-group":"ads","operationId":"createAdAudience","tags":["Ad Audiences"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"Create custom audience","description":"Creates a custom audience from a customer list, website visitors, a lookalike, or people who engaged with your content.\n\n### Audience types by platform\n\n- `customer_list`: Meta, Google, X, LinkedIn, TikTok, Pinterest, and Reddit.\n- `website` (pixel/tag visitors): Meta, TikTok, Pinterest, Google, and Reddit.\n- `lookalike`: Meta, TikTok, Pinterest and Google (Reddit's API cannot create one).\n- `meta_engagement`: Meta-only.\n- `tiktok_engagement`: TikTok-only.\n- `pinterest_engagement`: Pinterest-only.\n- `company_list`, `engagement` and `website_retargeting`: LinkedIn-only.\n\nA type sent to a platform that does not support it is a 422 `FEATURE_NOT_AVAILABLE`. Reddit audience names need at least 3 characters.\n\n### Per-platform rules for `website`\n\n- Meta: `pixelId` required, `retentionDays` 1-180, optional `urlContains` or raw `rule`. `event` is not accepted.\n- TikTok: `pixelId` required, `retentionDays` one of 7, 14, 30, 60, 90, 180. `event` is a TikTok pixel event (see below), optional `urlContains`.\n- Pinterest: `pixelId` is the Pinterest tag id, `retentionDays` 1-540, optional `event` (e.g. `checkout`, `addtocart`). Pinterest matches URLs exactly, so `urlContains` is a 400 there.\n- Google: no `pixelId` (the account's Google tag is used), `retentionDays` 1-540, `urlContains` defaults to `/` (all visitors). Built as a rule-based user list with prepopulation requested.\n- Reddit: `pixelId` is the Reddit pixel id, `retentionDays` 1-90. `event` is a Reddit conversion event (see below); any other value is sent as a custom event name. `urlContains` and `rule` are a 400.\n\nTikTok pixel events: `PAGE BROWSE` (default), `CLICK BUTTON`, `PIXEL SUBMIT FORM`, `CONTACT`, `DOWNLOAD`, `PIXEL ADD PAYMENT INFO`, `COMPLETE PAYMENT`, `INITIATE CHECKOUT`, `COMPLETE REGISTRATION`, `PRODUCT DETAIL PAGE BROWSE`, `PIXEL SEARCH`, `PIXEL ADD TO CART`, `PLACE AN ORDER`, `PIXEL ADD TO WISHLIST`, `PIXEL SUBSCRIBE`.\n\nReddit conversion events: `PAGE_VISIT` (default), `VIEW_CONTENT`, `SEARCH`, `ADD_TO_CART`, `ADD_TO_WISHLIST`, `PURCHASE`, `LEAD`, `SIGN_UP`.\n\n### Per-platform rules for `lookalike`\n\n- Meta: `ratio` (0.01-0.20).\n- Pinterest: `ratio` in whole percents (0.01-0.10) and `country` US, CA or GB.\n- TikTok and Google: `size` (narrow, balanced, broad) instead of `ratio`. TikTok needs a seed with at least 1,000 matched people.\n\n### Saved targeting\n\n`saved_targeting` stores a reusable TargetingSpec (no member upload, no adAccountId) that you reference later via `savedTargetingId` on `POST /v1/ads/create`.\n\n### How the audience gets filled\n\n- `customer_list` is created empty. Add members with `POST /v1/ads/audiences/{audienceId}/users`. On TikTok and Pinterest the audience is provisioned lazily on that first upload (until then its status is `pending`).\n- `company_list` is filled AT CREATION from the `companies` array below, which is required. To change the list afterwards, send the new full list to `POST /v1/ads/audiences/{audienceId}/companies` (a replace, not a merge). The `/users` endpoint rejects these audiences with a 422.\n- `website`, `website_retargeting`, `engagement`, `meta_engagement`, `tiktok_engagement`, `pinterest_engagement` and `lookalike` fill themselves from the pixel, engagement source or seed audience you point them at. They take no member upload at all.\n\nCreate is not idempotent, never auto-retry.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"UploadedOrDerivedAudience","description":"customer_list, website, lookalike or engagement audience (uploaded or derived from a source).","required":["accountId","adAccountId","name","type"],"properties":{"accountId":{"type":"string"},"adAccountId":{"type":"string","description":"Platform ad account ID. Must start with act_ for Meta; bare platform id for others (Google customer id, X/TikTok/LinkedIn/Pinterest account id)."},"name":{"type":"string","maxLength":255},"description":{"type":"string"},"type":{"type":"string","enum":["customer_list","company_list","engagement","meta_engagement","tiktok_engagement","pinterest_engagement","website","website_retargeting","lookalike"]},"matchRules":{"type":"array","minItems":1,"maxItems":50,"description":"Required for website_retargeting audiences (LinkedIn only).\nEach rule is a URL pattern; a member who visits any\nmatching page enters the segment. Needs the LinkedIn\nInsight Tag installed on the customer's site; the\nsegment only starts filling once the tag reports visits.\n\nThe response's `platformAudienceId` is the LinkedIn\nadSegment id, valid for downstream use.\nThese segments appear in GET /v1/ads/audiences with \n`type: website_retargeting` once LinkedIn has finished building them.\n","items":{"type":"object","additionalProperties":false,"required":["matchType","matchValue"],"properties":{"matchType":{"type":"string","enum":["EXACT","STARTS_WITH","CONTAINS","ENDS_WITH"]},"matchValue":{"type":"string"}}}},"sourceType":{"type":"string","enum":["VIDEO_ADS","LEAD_GEN_FORMS","ORGANIZATION_PAGES","EVENT_PAGES","SINGLE_IMAGE_ADS"],"description":"Required for engagement audiences (LinkedIn only): what\nmembers engaged with: a video/leadgen/single-image ad\ncampaign, a Company Page or an Event page.\n"},"trigger":{"type":"string","description":"Required for engagement audiences. The action, validated\nby LinkedIn against `sourceType`. Common values:\nVIDEO_ADS FIRST_QUARTILE / MIDPOINT / THIRD_QUARTILE /\nFULL_COMPLETE; LEAD_GEN_FORMS VIEW_FORM /\nLEAD_FORM_SUBMIT; ORGANIZATION_PAGES VIEW / CTA_CLICK;\nEVENT_PAGES RSVPED / VIDEO_VIEWED / ENGAGEMENT / CLICK.\n"},"lookbackDays":{"type":"integer","enum":[30,60,90,180,365],"description":"Required for engagement audiences. Rolling window."},"engagementSources":{"type":"array","minItems":1,"maxItems":50,"description":"Required for engagement audiences. Campaign URNs for the\nad source types, organization URNs for pages and events.\nLinkedIn creates one rule per source, all sharing the\nsame trigger and lookbackDays.\n","items":{"type":"string"}},"companies":{"type":"array","minItems":1,"maxItems":300000,"description":"Required for company_list audiences (LinkedIn only). Plain-text company rows for account targeting; each row needs at least one identifier.\n\n- Not hashed: LinkedIn matches these against its own company graph.\n- LinkedIn recommends 1,000+ companies for a usable match rate and takes up to 48h to process the list.\n- Replace the list later with POST /v1/ads/audiences/{audienceId}/companies.\n","items":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":255},"domain":{"type":"string","maxLength":100},"website":{"type":"string","maxLength":100},"linkedinPageUrl":{"type":"string"}}}},"pixelId":{"type":"string","description":"website: the Meta pixel, TikTok pixel, Pinterest tag or Reddit pixel id. Required on those four, rejected on Google."},"retentionDays":{"type":"integer","minimum":1,"maximum":540,"description":"Required for website (Meta max 180, TikTok 7/14/30/60/90/180, Reddit max 90, Pinterest and Google max 540), meta_engagement (max 365) and tiktok_engagement (7/14/30/60/90/180; organic and live video and most business-account events only 7/14/30)."},"engagementSource":{"type":"string","enum":["page","instagram","video"],"description":"Required for meta_engagement audiences (Meta only): what people\nengaged with. `page` = a Facebook Page, `instagram` = an IG\nprofessional account, `video` = a video.\n"},"sourceId":{"type":"string","description":"Required for meta_engagement: the Page / IG account / video id."},"event":{"type":"string","maxLength":100,"description":"The event to match. Its meaning depends on the type:\n\n- meta_engagement: the engagement event. Defaults per source (page → page_engaged, instagram → ig_business_profile_all, video → video_watched). Ignored when `rule` is provided.\n- website on Reddit: the conversion event (default `PAGE_VISIT`), or a custom event name.\n- website on TikTok: the pixel event (default `PAGE BROWSE`).\n- website on Pinterest: the tag event (`pagevisit`, `signup`, `checkout`, `viewcategory`, `search`, `addtocart`, `watchvideo`, `lead`, `custom` or a partner-defined event).\n- tiktok_engagement (required): the TikTok engagement event, validated per `source` (TikTok's filter values, spaces included). An unknown value is a 400 that lists the valid ones.\n\nValid tiktok_engagement values per `source`:\n\n- ads: `CLICK`, `IMPRESSION`, `PLAY 2S`, `PLAY 6S`, `PLAY 25`, `PLAY 50`, `PLAY 75`, `PLAY OVER`, and the `ENGAGEMENT APP PROFILE` / `ENGAGEMENT TIKTOK INSTANT` / `ENGAGEMENT COLLECTION ADS` `CLICK` and `IMPRESSION` events.\n- organic_video: `ORGANIC VIDEO PLAY 2S`, `ORGANIC VIDEO PLAY 6S`, `ORGANIC VIDEO PLAY OVER`, `ORGANIC VIDEO ENGAGEMENT`.\n- live_video: `LIVE VIDEO VIEW`, `LIVE VIDEO ENGAGEMENT`.\n- business_account: `BUSINESS ACCOUNT PROFILE FOLLOW`, `BUSINESS ACCOUNT PROFILE VISIT`, `BUSINESS ACCOUNT ENGAGEMENT`, `BUSINESS ACCOUNT PLAY 2S`, `BUSINESS ACCOUNT PLAY 6S`, `BUSINESS ACCOUNT PLAY OVER`.\n"},"sourceAudienceId":{"type":"string","description":"Required for lookalike audiences"},"country":{"type":"string","description":"2-letter code, required for lookalike audiences"},"ratio":{"type":"number","minimum":0.01,"maximum":0.2,"description":"lookalike on Meta (0.01-0.20) and Pinterest (0.01-0.10, whole percents). Rejected on TikTok and Google."},"size":{"type":"string","enum":["narrow","balanced","broad"],"description":"lookalike on TikTok and Google: audience breadth. Rejected on Meta and Pinterest."},"source":{"type":"string","enum":["ads","organic_video","live_video","business_account"],"description":"Required for tiktok_engagement: what people engaged with."},"sourceIds":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"},"description":"tiktok_engagement: ad group ids for `ads`, TikTok post ids (`item_id`) for `organic_video` and live video ids for `live_video` (max 10 for both). Not accepted for `business_account`: Zernio sends the core_user_id of the TikTok for Business user that connected the ad account."},"identityId":{"type":"string","description":"tiktok_engagement: the TikTok identity (TT_USER or BC_AUTH_TT) that owns the videos. Required for organic_video and live_video."},"identityType":{"type":"string","enum":["TT_USER","BC_AUTH_TT"],"description":"tiktok_engagement: type of `identityId`."},"identityAuthorizedBcId":{"type":"string","description":"tiktok_engagement: required when identityType is BC_AUTH_TT."},"engagerType":{"type":"integer","enum":[1,2],"description":"pinterest_engagement: Pinterest's `engager_type`, passed through when set."},"engagementType":{"type":"string","enum":["click","save","closeup","comment","like"],"description":"pinterest_engagement: limit to one engagement action."},"engagementDomains":{"type":"array","items":{"type":"string"},"description":"pinterest_engagement: people who engaged with Pins from these domains. The domain must be claimed on the Pinterest account or Pinterest rejects it."},"campaignIds":{"type":"array","items":{"type":"string","pattern":"^\\d+$"},"description":"pinterest_engagement: people who engaged with these campaigns' ads."},"adIds":{"type":"array","items":{"type":"string","pattern":"^\\d+$"},"description":"pinterest_engagement: people who engaged with these ads."},"pinIds":{"type":"array","items":{"type":"string","pattern":"^\\d+$"},"description":"pinterest_engagement: people who engaged with these Pins. At least one of engagementDomains, campaignIds, adIds or pinIds is required."},"urlContains":{"type":"string","description":"website on Meta, TikTok and Google. Narrows the audience from all visitors\nto visitors of URLs containing this substring. Ignored when `rule` is\nsupplied. A 400 on Pinterest, which only matches exact URLs.\n"},"rule":{"type":"object","description":"Meta only (a 400 elsewhere). Optional raw Meta rule, replacing the one we build. Omit it for all visitors of `pixelId`, or use `urlContains` for the common page-match case.\n\n**For `website`** this is Meta's Flexible Audience Rule and is VALIDATED before we call Meta.\n\nEvery entry in `inclusions.rules` (and `exclusions.rules`) must carry `event_sources`, `retention_seconds` AND `filter`. Meta rejects a rule missing any of the three with code 100 / subcode 1713098 (\"Invalid rule JSON format\"), so a bad shape is a 400 here instead.\n\nThe pre-2018 flat shapes (`{url: ...}`, `{event: ...}`) are not accepted by Meta at all (subcode 1870029).\n\nExample, visitors of /checkout in the last 30 days:\n\n`{\"inclusions\":{\"operator\":\"or\",\"rules\":[{\"event_sources\":[{\"id\":\"<pixelId>\",\"type\":\"pixel\"}],\"retention_seconds\":2592000,\"filter\":{\"operator\":\"and\",\"filters\":[{\"field\":\"url\",\"operator\":\"i_contains\",\"value\":\"/checkout\"}]}}]}}`\n\nMeta DERIVES `retention_days` from `retention_seconds` and stores `event_sources[].id` as a number, so a rule read back will not be byte-identical to the one you sent.\n\n**For `meta_engagement`** the rule is forwarded verbatim and NOT validated: that type has two dialects (the `video` source uses a legacy flat array), so no single schema covers both.\n"},"customerFileSource":{"type":"string","description":"Data source declaration for GDPR compliance (customer_list only)"}}},{"type":"object","title":"SavedTargetingAudience","description":"A reusable, stored TargetingSpec. No member upload step, no adAccountId, the spec is the audience. Reference it later via `savedTargetingId` on POST /v1/ads/create.","required":["type","accountId","name","spec"],"properties":{"type":{"type":"string","enum":["saved_targeting"]},"accountId":{"type":"string","description":"Account ID on the target ad platform."},"name":{"type":"string","maxLength":255},"description":{"type":"string"},"spec":{"allOf":[{"$ref":"#/components/schemas/TargetingSpec"}],"description":"The targeting spec to store."}}}]}}}},"responses":{"201":{"description":"Audience created","content":{"application/json":{"schema":{"type":"object","properties":{"audience":{"type":"object"},"message":{"type":"string"}}}}}},"400":{"description":"Missing required fields"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: enable Ads access or add the account to the connection's selection.","description":"Ads access required. Legacy plans need the Ads add-on; it is included by default on usage-based plans.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/ads/audiences/{audienceId}":{"get":{"x-resource-group":"ads","operationId":"getAdAudience","tags":["Ad Audiences"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"Get audience details","description":"Shows a custom audience's details, including its latest data from the ad platform when available.\n\nReturns the local audience record and fresh data from Meta (if available).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"audienceId","in":"path","required":true,"schema":{"type":"string"},"description":"The Zernio audience id (the id field of GET /v1/ads/audiences), not the platform segment id."}],"responses":{"200":{"description":"Audience details","content":{"application/json":{"schema":{"type":"object","properties":{"audience":{"type":"object"},"platformData":{"type":["object","null"],"description":"Fresh data from the platform API"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Forbidden. One of:\n\n- Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.\n- Code `ad_account_not_selected`: the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"x-resource-group":"ads","operationId":"updateAdAudience","tags":["Ad Audiences"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x"],"summary":"Update an audience","description":"Renames or redescribes an audience, or replaces a saved targeting audience's rules; platform audience rules cannot change.\n\n### `saved_targeting` audiences\n\nThey accept `name`, `description`, and `spec`. `spec` is a full replacement (no merge), Zernio-only, with no platform call.\n\nAds already created from a saved_targeting audience are unaffected: they snapshot the targeting at creation.\n\n### Platform audiences (uploaded/website/lookalike)\n\n- They accept `name` and `description` only, updated on the platform first and then mirrored locally.\n- Their rules are immutable, so `spec` returns 400 for them.\n- Platform audience updates are Meta-only for now (other platforms return 501).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"audienceId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"At least one field is required.","properties":{"name":{"type":"string","maxLength":255},"description":{"type":"string"},"spec":{"allOf":[{"$ref":"#/components/schemas/TargetingSpec"}],"description":"Full replacement for the stored targeting spec."}}}}}},"responses":{"200":{"description":"Audience updated","content":{"application/json":{"schema":{"type":"object","properties":{"audience":{"type":"object"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid body (no fields provided, malformed spec, or spec on a platform audience)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: enable Ads access or add the account to the connection's selection.","description":"Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix it, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The audience has no platform counterpart to update"},"501":{"description":"Platform audience updates are only supported on Meta"}}},"delete":{"x-resource-group":"ads","operationId":"deleteAdAudience","tags":["Ad Audiences"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"Delete custom audience","description":"Removes a custom audience from its ad platform (archiving it where the platform does not delete).\n\nRemoves the audience on its ad platform, then deletes the Zernio record.\n\n### By platform\n\n- Deleted: Meta, Google, TikTok, LinkedIn list and engagement segments, X, and Reddit.\n- Archived (how those platforms remove them): Pinterest audiences and LinkedIn `website_retargeting` segments.\n- Local only: `saved_targeting` audiences exist only on Zernio, so only the local record is removed.\n\nGoogle Ads does not allow removing lookalike lists through its API, so those return 422 `FEATURE_NOT_AVAILABLE`.\n\n### Failures and retries\n\nIf the platform refuses, the error is returned and the Zernio record is kept, so a retry is safe. An audience the platform no longer has counts as removed.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"audienceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Audience deleted","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: enable Ads access or add the account to the connection's selection.","description":"Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The platform does not allow removing this audience through its API (Google lookalike lists), or refused the removal."}}}},"/v1/ads/audiences/{audienceId}/users":{"post":{"x-resource-group":"ads","operationId":"addUsersToAdAudience","tags":["Ad Audiences"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","x","reddit"],"summary":"Add users to audience","description":"Uploads customer emails (and phone numbers on Meta) to a customer list audience, hashed before they are sent.\n\nData is SHA256-hashed server-side before sending to the platform. Max 10,000 users per request.\n\n### Per-platform behavior\n\n- **All platforms**: email is used everywhere. Phone is used on Meta only (other platforms ignore it).\n- **TikTok and Pinterest**: the first upload also provisions the audience (deferred create).\n- **LinkedIn**: uploads are full-replace.\n- **Reddit**: see below.\n\n### Reddit\n\n- Emails are lowercased and trimmed before hashing, duplicates are sent once, and the upload goes out in batches of 2,500.\n- Reddit matches by email only: rows without a valid email count in `numInvalid`, and a request where no row has one is a 400.\n- Reddit audiences need the `redditads` connection, not the Reddit posting account (422).\n\n### Audience types\n\ncustomer_list only. A LinkedIn `company_list` audience takes company rows, not people: send those to `POST /v1/ads/audiences/{audienceId}/companies`. This endpoint 422s for every other audience type.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"audienceId","in":"path","required":true,"schema":{"type":"string"},"description":"The Zernio audience id (the id field of GET /v1/ads/audiences), not the platform segment id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["users"],"properties":{"users":{"type":"array","maxItems":10000,"items":{"type":"object","properties":{"email":{"type":"string","format":"email"},"phone":{"type":"string"}},"description":"Each user must have at least email or phone"}}}}}}},"responses":{"200":{"description":"Users added","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"numReceived":{"type":"integer"},"numInvalid":{"type":"integer","description":"Rows the platform could not read. Returned on Meta, and on Reddit for rows without a valid email."}}}}}},"400":{"description":"Invalid input (malformed audienceId, empty users array, missing email/phone)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Ads access required. Legacy plans need the Ads add-on; it is included by default on usage-based plans.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection), or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Audience is not a customer_list type or has no platform ID yet"}}},"delete":{"x-resource-group":"ads","operationId":"removeUsersFromAdAudience","tags":["Ad Audiences"],"x-platforms":["meta","reddit"],"summary":"Remove users from audience","description":"Removes customer emails (and phone numbers on Meta) from a Meta or Reddit customer list audience. Same body as\n`POST /v1/ads/audiences/{audienceId}/users`: send plaintext rows, they are normalized and\nSHA256-hashed server-side exactly like an upload, so a row removes the person it added.\n\nMeta and Reddit only, customer_list only. Every other platform returns 422 with code `feature_not_available`,\nand every other audience type returns 422. Max 10,000 users per request. The platform applies the removal\nasynchronously, so the audience size does not drop immediately. On Reddit `invalidEntrySamples` is always empty.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"audienceId","in":"path","required":true,"schema":{"type":"string"},"description":"The Zernio audience id (the id field of GET /v1/ads/audiences), not the platform segment id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["users"],"properties":{"users":{"type":"array","minItems":1,"maxItems":10000,"items":{"type":"object","properties":{"email":{"type":"string","format":"email"},"phone":{"type":"string"}},"description":"Each user must have at least email or phone"}}}}}}},"responses":{"200":{"description":"Users removed","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"numReceived":{"type":"integer","description":"Rows the platform received."},"numInvalid":{"type":"integer","description":"Rows the platform could not read."},"invalidEntrySamples":{"type":"object","additionalProperties":{"type":"string"},"description":"A sample of the rows Meta could not read, passed through as Meta returns it. Empty when every row was valid."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: add it to the connection's selection or use another connection.","description":"Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix it, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The audience is not a customer_list, is not on Meta or Reddit (code `feature_not_available`), or has no platform ID yet."}}}},"/v1/ads/audiences/{audienceId}/companies":{"post":{"x-resource-group":"ads","operationId":"replaceAdAudienceCompanies","tags":["Ad Audiences"],"x-platforms":["linkedin"],"summary":"Replace audience companies","description":"Upload the company rows of a LinkedIn `company_list` audience (account-based marketing). LinkedIn-only, every other platform returns 422.\n\nThe initial list is sent with `companies` on `POST /v1/ads/audiences`; this endpoint is for every change after that.\n\n### Send the full list every time\n\nA LinkedIn audience segment holds exactly one uploaded list, so the list you send here REPLACES the segment's list instead of being appended to it. Always send the full set of companies.\n\nLinkedIn returns only the identifier of the uploaded file, never its rows, so the merge cannot be done for you. Keep the source list on your side.\n\n### How the matching behaves\n\n- Rows are plain text (not hashed), matched against LinkedIn's own company graph.\n- Matching is asynchronous: LinkedIn takes up to 48h for a new audience and up to 24h for a later update, and the audience stays `processing` meanwhile.\n- LinkedIn does not document how quickly companies dropped from the list stop being targeted, so treat removals as eventual rather than immediate.\n- LinkedIn recommends at least 1,000 companies for a usable match rate, and caps a list at 300,000.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"audienceId","in":"path","required":true,"schema":{"type":"string"},"description":"The Zernio audience id (the id field of GET /v1/ads/audiences), not the platform segment id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["companies"],"properties":{"companies":{"type":"array","minItems":1,"maxItems":300000,"description":"The complete company list. Each row needs at least one of name, domain, website or linkedinPageUrl.","items":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":255},"domain":{"type":"string","maxLength":100},"website":{"type":"string","maxLength":100},"linkedinPageUrl":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Companies uploaded","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"numReceived":{"type":"integer","description":"Rows sent to LinkedIn. Matching happens asynchronously, so this is not the matched company count."}}}}}},"400":{"description":"Invalid input (malformed audienceId, empty companies array, a row with no identifier)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: enable Ads access or add the account to the connection's selection.","description":"Ads access required. Legacy plans need the Ads add-on; it is included by default on usage-based plans.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Audience is not a company_list type, is not on LinkedIn, or has no platform ID yet"}}}},"/v1/ads/conversions/quality":{"get":{"x-resource-group":"ads","operationId":"getConversionsQuality","tags":["Conversions"],"x-platforms":["meta","pinterest"],"summary":"Get Event Match Quality","description":"Shows how well your server-side conversion events match users, with event match quality and coverage for Meta or Pinterest.\n\nReads Meta Event Match Quality (EMQ) and pixel↔CAPI event coverage for a\npixel/dataset, live from Meta's Dataset Quality API. Web events only (a\nMeta limitation). Other platforms return 405, except Pinterest. Requires the Ads add-on.\n\nPinterest (`pinterestads`): `destinationId` is the numeric ad account id. Rows come from\nPinterest's Event Quality Score for Conversions API web events over the last 14 days,\none per event name, with each identifier's coverage in `matchKeys` and\n`eventCoveragePercentage` set to the tag/API `event_id` overlap. No `compositeScore`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"SocialAccount _id (a metaads or pinterestads account)."},{"name":"destinationId","in":"query","required":true,"schema":{"type":"string"},"description":"Meta pixel/dataset ID, or the numeric Pinterest ad account id."}],"responses":{"200":{"description":"Match-quality rows, one per event name.","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","example":"metaads"},"rows":{"type":"array","items":{"type":"object","properties":{"eventName":{"type":"string"},"compositeScore":{"type":"number","description":"Composite EMQ score, 0-10."},"matchKeys":{"type":"array","items":{"type":"object","properties":{"identifier":{"type":"string"},"coveragePercentage":{"type":"number"}}}},"eventCoveragePercentage":{"type":"number","description":"Pixel↔CAPI coverage rate for this event."}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"405":{"description":"Platform does not expose Event Match Quality (neither Meta nor Pinterest)."},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/ads/conversions":{"post":{"x-resource-group":"ads","operationId":"sendConversions","tags":["Conversions"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","reddit"],"summary":"Send conversion events","description":"Sends conversion events, such as purchases or leads, from your server to an ad platform so it can attribute and optimize ads.\n\nRelays one or more events to the target ad platform's native Conversions API. The platform is inferred from the provided `accountId`. Requires the Ads add-on.\n\n### Supported platforms\n\n- Meta (`metaads`) via Graph API\n- Google Ads (`googleads`) via Data Manager API `ingestEvents`\n- LinkedIn (`linkedinads`) via `/rest/conversionEvents`\n- TikTok (`tiktokads`) via the Offline Events API `/offline/batch/` (OFFLINE conversions only)\n- OpenAI Ads (`openaiads`) via its Conversions API (a separate host, `bzr.openai.com`)\n- Pinterest (`pinterestads`) via `POST /v5/ad_accounts/{id}/events`\n- Reddit (`redditads`) via the Reddit Conversions API (`POST /api/v3/pixels/{pixelId}/conversion_events`)\n\n### `destinationId` per platform\n\n- Meta: pixel (dataset) ID, e.g. `123456789012345`\n- Google: conversion action resource name, e.g. `customers/1234567890/conversionActions/987654321`\n- LinkedIn: conversion rule ID or URN, e.g. `104012` or `urn:lla:llaPartnerConversion:104012`\n- TikTok: Offline Event Set ID, e.g. `7057103914977558530`\n- OpenAI Ads: pixel wire id (numeric `pixel_id`, distinct from the internal pixel id), as returned by `GET /v1/accounts/{accountId}/conversion-destinations`\n- Pinterest: numeric ad account id, e.g. `549755885175` (Pinterest attributes to the ad account, not to a tag)\n- Reddit: pixel id, e.g. `a2_abc123`, as returned by `GET /v1/accounts/{accountId}/conversion-destinations` (any other shape returns 400)\n\nCallers can list valid destinations via `GET /v1/accounts/{accountId}/conversion-destinations`.\n\n### Pinterest notes\n\n- Each event needs an `email`, or `ipAddress` plus `userAgent`. Others are listed in `failures` with code `INVALID_EVENT` and the rest are still sent.\n- `clickIds.epik` (the `_epik` cookie) is sent as `click_id`.\n- `actionSource` `web` stays `web`, offline sources become `offline`, and app events need `platformData.action_source` `app_android` or `app_ios`.\n- Pinterest answers per event, so one bad event does not fail its chunk (failures carry code `PINTEREST_EVENT_FAILED`).\n- `consent.adUserData: DENIED` sets `opt_out`.\n- The connected user needs a Business Access role on the ad account (403 otherwise).\n\n### Reddit notes\n\n- Each event needs a match key: `clickIds.rdt_cid`, `clickIds.rdt_uuid`, `email`, `phone`, `externalId`, or `ipAddress` plus `userAgent`.\n- Reddit accepts events up to 7 days old. `eventTime` is unix SECONDS (a value more than an hour in the future is refused as milliseconds).\n- Events failing these checks are listed in `failures` with code `INVALID_EVENT` and the rest are still sent.\n- Email (lowercased, dots and `+tags` stripped from the local part), phone (E.164 with the leading `+`) and `externalId` are SHA-256 hashed. IP and user agent go plaintext.\n- `consent.adUserData: DENIED` sends no user fields.\n- `actionSource` maps to WEBSITE (`web`), APP (`app`) or OTHER, overridable with `platformData.action_source`. `platformData.order_id` is forwarded.\n- `testCode` is sent as Reddit's `test_id`.\n\nReddit errors:\n\n- 403 `reconnect_required`: the connection was authorized without the `adsconversions` permission (reconnect via GET /v1/connect/redditads/ads).\n- 403 `insufficient_permissions`: the Reddit user has no role on the ad account that owns the pixel.\n- `REDDIT_REJECTED`: Reddit throttling and other rejections, reported per chunk in `failures`.\n\n### TikTok notes\n\nThis path sends OFFLINE conversions (in-store / CRM / call-center), not web-pixel events. Each event must carry an email or phone (TikTok requires at least one).\n\nThe connected TikTok ads account must have granted the Offline Events permission; older grants must reconnect.\n\n### OpenAI Ads notes\n\nRequires a tracking tag (pixel) to already exist on the account. Returns 422 with code `TRACKING_TAG_REQUIRED` if `POST /v1/accounts/{accountId}/tracking-tags` hasn't been called yet.\n\n### Hashing\n\nAll PII (email, phone, names, external IDs) is hashed with SHA-256 server-side per each platform's normalization spec, including Google's Gmail-specific dot/plus-suffix stripping. Send plaintext.\n\nLinkedIn `externalIds` are passed through as plaintext per LinkedIn's spec; only emails and phones are hashed.\n\nFor LinkedIn, the connected account must have been authorized after the Conversions API rollout (the OAuth grant must include `rw_conversions`). Older accounts must reconnect.\n\n### Batching\n\nBatching is handled automatically. Per-platform caps:\n\n- Meta: 1000 events per request; rejects the entire batch if any event is malformed.\n- Google: 2000.\n- LinkedIn: 5000, all-or-nothing per chunk.\n- OpenAI Ads: 1000 per request. Larger submissions are split into 1000-event chunks, each all-or-nothing (a malformed event fails every event in that chunk, not the whole request).\n- Reddit: works the same way as OpenAI Ads, in chunks of 1000.\n\n### Dedup\n\nPass a stable `eventId` on every event:\n\n- Meta and LinkedIn use it to dedupe against browser-side pixel/Insight Tag events.\n- Google maps it to `transactionId`.\n- Reddit receives it as `conversion_id`, its dedup key against Reddit Pixel events.\n\n### `eventName` per platform\n\n- Meta: free-form. Standard names (Purchase, Lead, ...) match Meta's built-in events; custom strings are accepted.\n- Google: ignored. The conversion action's category determines the event type. Send the standard name closest to your action for documentation, but the platform will not branch on it.\n- LinkedIn: ignored. The conversion rule's `type` (LEAD, PURCHASE, etc.) is locked to the destination at rule-creation time. Send the standard name for documentation; LinkedIn does not branch on it.\n- OpenAI Ads: a fixed subset of standard names maps 1:1 onto OpenAI's own event-type enum: Purchase, Lead, AddToCart, ViewContent, InitiateCheckout, CompleteRegistration, Subscribe, StartTrial, Schedule. Any other standard name or custom string is sent as `type: custom` with the name preserved.\n- Pinterest: standard names map onto Pinterest's (see below). Any other string is sent as is, so it matches an advertiser defined event of that name.\n\nPinterest name mapping:\n\n- Purchase = `checkout`\n- AddToCart = `add_to_cart`\n- InitiateCheckout = `initiate_checkout`\n- AddPaymentInfo = `add_payment_info`\n- Lead = `lead`\n- CompleteRegistration = `signup`\n- Subscribe = `subscribe`\n- ViewContent = `view_content`\n- Search = `search`\n- PageView = `page_visit`\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","destinationId","events"],"properties":{"accountId":{"type":"string","description":"SocialAccount ID (metaads, googleads, linkedinads, tiktokads, openaiads, pinterestads, or redditads)."},"destinationId":{"type":"string","description":"Platform destination identifier. For Meta, the pixel/dataset\nID. For Google, the conversion action resource name. For\nLinkedIn, the conversion rule ID or full\n`urn:lla:llaPartnerConversion:{id}` URN. For OpenAI Ads, the\npixel wire id. For Pinterest, the numeric ad account id. For\nReddit, the pixel id (`a2_...`).\n"},"events":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/ConversionEvent"}},"testCode":{"type":"string","description":"Test event code. Send it at the request root, never inside an event. A root-level `test_event_code` (Meta's own name) is accepted as an alias and must be a non-empty string; sending both with different values is a 400.\n\n- Meta: sent as `test_event_code`. Events show in Events Manager's Test Events tab for the pixel whose current test code matches (Meta rotates the code, so copy it again from that tab). Meta still processes them like any other event, so remove it in production.\n- Pinterest: any value sends the batch with `test=true` (validated, not recorded).\n- Reddit: sent as `test_id`, so the events show in the pixel's test view.\n- Google, LinkedIn and OpenAI Ads: ignored.\n"},"consent":{"type":"object","description":"Batch-level user consent. Required by Google for EEA/UK events under the Feb 2026 restrictions.\n\n- **Meta:** any DENIED flag enables Limited Data Use on every event in the batch (data_processing_options [\"LDU\"] with geolocation, country 0 / state 0). GRANTED or absent consent sends events with Meta's default processing.\n- **Reddit:** `adUserData: DENIED` drops every user field from the events.\n- **LinkedIn:** ignored.\n","properties":{"adUserData":{"type":"string","enum":["GRANTED","DENIED"]},"adPersonalization":{"type":"string","enum":["GRANTED","DENIED"]}}}}}}}},"responses":{"200":{"x-summary":"The events were processed: inspect `failures` to find any events that failed.","description":"Events processed. Inspect `eventsFailed` and `failures[]` to detect partial failure.\n\n- Meta: a batch is all-or-nothing (either every event in a chunk succeeds, or every event in the chunk is listed in failures).\n- Google: success/failure is reported at the request level only.\n- OpenAI Ads and Reddit: each 1000-event chunk is all-or-nothing, same as Meta.\n","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["metaads","googleads","linkedinads","tiktokads","openaiads","pinterestads","redditads"]},"eventsReceived":{"type":"integer","description":"Events accepted by the platform."},"eventsFailed":{"type":"integer","description":"Events rejected (see failures)."},"failures":{"type":"array","items":{"type":"object","properties":{"eventIndex":{"type":"integer","description":"Index into the submitted events array."},"eventId":{"type":"string","description":"Echoes back the eventId of the failed event."},"message":{"type":"string"},"code":{"oneOf":[{"type":"string"},{"type":"integer"}]},"platformError":{"type":"object","additionalProperties":true,"description":"Meta only. Meta's own error for the rejected chunk, with credentials\nredacted: `message`, `type`, `code`, `error_subcode`, `error_user_title`,\n`error_user_msg` and `fbtrace_id` when Meta sends them. `message` above\nalready ends with `error_user_msg`. Absent when Meta returned no error body.\n"}}}},"traceId":{"type":"string","description":"Platform trace ID for debugging. fbtrace_id for Meta,\nrequestId for Google. Absent for LinkedIn (LinkedIn's\nconversionEvents endpoint does not surface a trace ID),\nOpenAI Ads and Reddit (no trace ID surfaced).\n"},"testCode":{"type":["string","null"],"description":"The test code sent to the platform, as received (from `testCode` or `test_event_code`). `null` when the request carried none, so the events were sent as production events."}}}}}},"400":{"x-summary":"The body is invalid or the destination customer is not on this connection: fix the request and resend.","description":"Invalid body (missing accountId/destinationId/events, malformed event shape, a `test_event_code` that is not a non-empty string, `testCode` and `test_event_code` with different values), or (Google Ads, param `destinationId`) the customer named in `destinationId` is not one of this connection's Google Ads accounts."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Access is denied: enable Ads access, reconnect the account to grant the missing permission, or select the ad account.","description":"Forbidden. One of:\n\n- Ads access required (Ads add-on on legacy plans, included on usage-based plans).\n- LinkedIn: the connected account lacks the `rw_conversions` scope and must be reconnected.\n- Reddit: the connection lacks the `adsconversions` permission (code `reconnect_required`, reconnect Reddit Ads), or the Reddit user has no role on the ad account that owns the pixel (code `insufficient_permissions`).\n- Google Ads: code `ad_account_not_selected`. The connection has selected ad accounts and the Google Ads customer named in `destinationId` is not among them (param `destinationId`; `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`).\n\nFor `ad_account_not_selected`, add the customer to the selection (GET /v1/connect/googleads/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"x-summary":"The account is not ready to receive conversions: create the missing tracking tag or fix the Google Ads connection, then retry.","description":"The account is not ready to receive conversions.\n\n- OpenAI Ads, code `TRACKING_TAG_REQUIRED`: no tracking tag (pixel) exists yet for this account. Create one via `POST /v1/accounts/{accountId}/tracking-tags` first.\n- Google Ads, code `ads_connection_required`: no Google Ads customer account is left on this connection after its ad-account selection. Reconnect via GET /v1/connect/googleads/ads with a Google user that can reach the ad account, or select one of its ad accounts.\n- Google Ads, code `invalid_resource_state`: the connection reaches only a Google Ads manager account with no client accounts yet. Create one with POST /v1/ads/accounts or under the manager in Google Ads, then retry.\n"},"429":{"x-summary":"The LinkedIn rate limit was reached: retry later with backoff.","description":"LinkedIn token-level rate limit hit (600 requests/min, 300k/day\nper token). Retry with backoff. Meta and Google have their own\nrate-limit semantics surfaced via platform-specific 4xx responses.\n"}}}},"/v1/ads/conversions/adjustments":{"post":{"x-resource-group":"ads","operationId":"adjustConversions","tags":["Conversions"],"x-platforms":["google"],"summary":"Adjust uploaded conversions","description":"Retracts, restates the value of, or enhances conversions you already sent to Google Ads, for refunds or late customer data.\n\nIt adjusts conversions previously uploaded via `POST /v1/ads/conversions`: retract them, restate their value, or enhance them with first-party data. Requires the Ads add-on.\n\n### Google Ads only\n\nGoogle handles adjustments through the classic Google Ads API (`ConversionAdjustmentUploadService`). The Data Manager `ingestEvents` path used for sending conversions is ingest-only. Meta and LinkedIn have no equivalent, so this endpoint returns `405` for those platforms.\n\n### Adjustment types\n\n- `RETRACTION`: remove the conversion entirely (refund, chargeback, cancelled order, churn).\n- `RESTATEMENT`: change the conversion's value (upgrade / downgrade / partial refund). Send the corrected **total** value in `restatementValue` (not a delta).\n- `ENHANCEMENT`: attach first-party identifiers (hashed email / phone) to an existing conversion (enhanced conversions applied after the fact).\n\n### Identifying the original conversion\n\nPer adjustment, send one of:\n\n- `orderId`: the transaction ID you sent as `eventId` on the original conversion. Recommended, and **required** for `ENHANCEMENT`.\n- `gclid` + `conversionTime`: the click ID and the original conversion's time (unix seconds). Not available for `ENHANCEMENT`.\n\n### Other fields\n\n- `destinationId` is the conversion action resource name, e.g. `customers/1234567890/conversionActions/987654321` (same value you send to `POST /v1/ads/conversions`).\n- PII in `user` is hashed with SHA-256 server-side (Gmail-specific normalization included). Send plaintext.\n- Times are unix seconds; we convert to Google's required `yyyy-MM-dd HH:mm:ss+00:00` format.\n\n### Limits\n\nUp to 2000 adjustments per request. Partial failure is supported (inspect `adjustmentsFailed` / `failures[]`).\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","destinationId","adjustments"],"properties":{"accountId":{"type":"string","description":"SocialAccount ID. Must be a `googleads` account."},"destinationId":{"type":"string","description":"Conversion action resource name, e.g. `customers/1234567890/conversionActions/987654321`."},"adjustments":{"type":"array","minItems":1,"maxItems":2000,"items":{"type":"object","required":["adjustmentType","adjustmentTime"],"properties":{"adjustmentType":{"type":"string","enum":["RETRACTION","RESTATEMENT","ENHANCEMENT"]},"adjustmentTime":{"type":"number","description":"When the adjustment occurred, unix seconds."},"orderId":{"type":"string","description":"Transaction ID of the original conversion (the `eventId` you sent). Recommended; required for ENHANCEMENT."},"gclid":{"type":"string","description":"Alternative key. The original click ID. Pair with `conversionTime`. Not valid for ENHANCEMENT."},"conversionTime":{"type":"number","description":"The original conversion's time, unix seconds. Required when identifying by `gclid`."},"restatementValue":{"type":"number","description":"RESTATEMENT only. The corrected TOTAL conversion value."},"currency":{"type":"string","description":"RESTATEMENT only. ISO 4217 currency for `restatementValue`."},"user":{"type":"object","description":"ENHANCEMENT only. First-party identifiers (hashed server-side). At least one of email/phone required.","properties":{"email":{"type":"string"},"phone":{"type":"string"}}},"userAgent":{"type":"string","description":"ENHANCEMENT only. The original conversion's user agent (improves match quality)."}}}}}}}}},"responses":{"200":{"x-summary":"The adjustments were processed: inspect `failures` to find any that failed.","description":"Adjustments processed. Inspect `adjustmentsFailed` and `failures[]` for\npartial failure (Google reports per-row errors via partial failure).\n","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["googleads"]},"adjustmentsReceived":{"type":"integer","description":"Adjustments accepted by Google."},"adjustmentsFailed":{"type":"integer","description":"Adjustments rejected (see failures)."},"failures":{"type":"array","items":{"type":"object","properties":{"adjustmentIndex":{"type":"integer","description":"Index into the submitted adjustments array."},"message":{"type":"string"},"code":{"oneOf":[{"type":"string"},{"type":"integer"}]}}}},"traceId":{"type":"string"}}}}}},"400":{"x-summary":"The body or an adjustment is invalid, or the destination customer is not on this connection: fix the request and resend.","description":"Invalid body, or a malformed adjustment (missing key, missing restatementValue for RESTATEMENT, missing identifiers for ENHANCEMENT), or (param `destinationId`) the customer named in `destinationId` is not one of this connection's Google Ads accounts."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Google Ads access is missing or the customer is not selected: enable Ads access or add the customer to the connection's selection.","description":"Ads access required (Ads add-on on legacy plans, included on usage-based plans).\n\nOr, for Google Ads, code `ad_account_not_selected`: the connection has selected ad accounts and the Google Ads customer named in `destinationId` is not among them (param `destinationId`; `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`).\n\nFix: add the customer to the selection (GET /v1/connect/googleads/ads with adAccountIds, which replaces the selection), or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"405":{"description":"Conversion adjustments are only available for Google Ads (the account's platform is not `googleads`)."},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"x-summary":"No Google Ads client account is usable on this connection: reconnect with a user who reaches one, or create one first.","description":"Google Ads errors:\n\n- `ads_connection_required`: no Google Ads customer account is left on this connection after its ad-account selection. Reconnect via GET /v1/connect/googleads/ads with a Google user that can reach the ad account, or select one of its ad accounts.\n- `invalid_resource_state`: the connection reaches only a Google Ads manager account with no client accounts yet. Create one with POST /v1/ads/accounts or under the manager in Google Ads, then retry.\n"}}}},"/v1/ads/conversions/actions":{"get":{"x-resource-group":"ads","operationId":"listConversionActions","tags":["Conversions"],"x-platforms":["google"],"summary":"List conversion actions","description":"Lists the conversion actions in a Google Ads account, with the website tag snippets to install where available.\n\nLists Google Ads conversion actions on the resolved customer, all types by\ndefault. Each action's `tagSnippets` (global site tag + event snippet) is\nincluded when Google has them for that action's type, e.g. `WEBPAGE`.\nGoogle-only; other platforms return `501`. Requires the Ads add-on.\n\n`adAccountId` (alias `customerId`) is optional: when omitted, it is resolved from the connection's\naccessible Google Ads customers, and the call fails with `400` when more than\none is accessible (pass `adAccountId` to disambiguate).\n\nThe list itself is cached for the quota window (1 hour fresh, up to 7 days\nlast-good; the cache key does not vary on `type`). The response carries\n`cachedAt` and `stale`, set when a quota-exhausted call falls back to the\nlast-good copy instead of a live read.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"SocialAccount _id (must be a googleads account)."},{"name":"adAccountId","in":"query","required":false,"schema":{"type":"string"},"description":"Platform ad account ID (Google customer ID, digits only). Resolved automatically when the connection has exactly one accessible customer."},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string"},"description":"Alias of adAccountId, kept for existing callers"},{"name":"type","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by Google's ConversionActionType enum (e.g. WEBPAGE, UPLOAD_CLICKS)."}],"responses":{"200":{"description":"The resolved customer and its conversion actions.","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","description":"The Google Ads customer id the actions were read from."},"actions":{"type":"array","items":{"$ref":"#/components/schemas/ConversionAction"}},"cachedAt":{"type":["string","null"],"format":"date-time","description":"When this list was fetched from Google. Null when it was never served from cache."},"stale":{"type":"boolean","description":"True when Google's daily API quota was exhausted and this is the last successful fetch, not a live read."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Google Ads access is missing or the customer is not selected: enable Ads access or add the customer to the connection's selection.","description":"Ads access required (Ads add-on on legacy plans, included on usage-based plans).\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted Google Ads customer is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add it to the selection (GET /v1/connect/googleads/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"x-summary":"No Google Ads client account is usable on this connection: reconnect with a user who reaches one, or create one first.","description":"Google Ads only. Two cases:\n\n- `ads_connection_required`: no Google Ads customer account is left on this connection after its ad-account selection. Reconnect via GET /v1/connect/googleads/ads with a Google user that can reach the ad account, or select one of its ad accounts.\n- `invalid_resource_state`: the connection reaches only a Google Ads manager account with no client accounts yet. Create one with POST /v1/ads/accounts or under the manager in Google Ads, then retry.\n"},"501":{"description":"Conversion actions are only available for Google Ads (the account's platform is not `googleads`)."}}},"post":{"x-resource-group":"ads","operationId":"createConversionAction","tags":["Conversions"],"x-platforms":["google"],"summary":"Create website conversion action","description":"Creates a Google Ads website conversion action and returns the tag snippets to install on your site.\n\nCreates a `WEBPAGE` conversion action (category `DEFAULT`) and returns it with\nits tag snippets, read back after creation since Google never returns them on\nthe create response itself. Invalidates the cached list `GET` on this resource\nwould otherwise keep serving. Google-only; other platforms return `501`.\nRequires the Ads add-on.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","name","type"],"properties":{"accountId":{"type":"string","description":"SocialAccount ID. Must be a `googleads` account."},"adAccountId":{"type":"string","description":"Platform ad account ID (Google customer ID, digits only). Resolved automatically when the connection has exactly one accessible customer."},"customerId":{"type":"string","deprecated":true,"description":"Alias of adAccountId, kept for existing callers"},"name":{"type":"string","minLength":1,"maxLength":100},"type":{"type":"string","enum":["WEBPAGE"],"description":"Only WEBPAGE is supported for creation today."},"defaultValue":{"type":"number","minimum":0,"description":"Default conversion value used when an event doesn't carry its own value."},"alwaysUseDefaultValue":{"type":"boolean","description":"When true, always use defaultValue and ignore any value sent with the event. Defaults to true when defaultValue is set."},"category":{"type":"string","enum":["DEFAULT","PAGE_VIEW","PURCHASE","SIGNUP","DOWNLOAD","ADD_TO_CART","BEGIN_CHECKOUT","SUBSCRIBE_PAID","PHONE_CALL_LEAD","IMPORTED_LEAD","SUBMIT_LEAD_FORM","BOOK_APPOINTMENT","REQUEST_QUOTE","GET_DIRECTIONS","OUTBOUND_CLICK","CONTACT","ENGAGEMENT","STORE_VISIT","STORE_SALE","QUALIFIED_LEAD","CONVERTED_LEAD"],"description":"conversion_action.category. Defaults to DEFAULT on create."},"countingType":{"type":"string","enum":["ONE_PER_CLICK","MANY_PER_CLICK"],"description":"ONE_PER_CLICK counts one conversion per ad click (leads); MANY_PER_CLICK counts every one (purchases)."},"defaultCurrency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 currency of defaultValue (value_settings.default_currency_code)."},"clickThroughLookbackWindowDays":{"type":"integer","minimum":1,"maximum":90,"description":"Days after an ad click a conversion still counts."},"viewThroughLookbackWindowDays":{"type":"integer","minimum":1,"maximum":30,"description":"Days after an ad view a view-through conversion still counts."},"primaryForGoal":{"type":"boolean","description":"true = primary (counts toward bidding when its goal is biddable), false = secondary."}}}}}},"responses":{"201":{"description":"The created conversion action, with its tag snippets.","content":{"application/json":{"schema":{"type":"object","properties":{"action":{"$ref":"#/components/schemas/ConversionAction"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the ad account is not selected: enable Ads access or add the account to the connection's selection.","description":"Ads access required (Ads add-on on legacy plans, included on usage-based plans).\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"x-summary":"No Google Ads client account is usable on this connection: reconnect with a user who reaches one, or create one first.","description":"Google Ads.\n\n- `ads_connection_required`: no Google Ads customer account is left on this connection after its ad-account selection. Reconnect via GET /v1/connect/googleads/ads with a Google user that can reach the ad account, or select one of its ad accounts.\n- `invalid_resource_state`: the connection reaches only a Google Ads manager account with no client accounts yet. Create one with POST /v1/ads/accounts or under the manager in Google Ads, then retry.\n"},"501":{"description":"Conversion actions are only available for Google Ads (the account's platform is not `googleads`)."}}}},"/v1/ads/conversions/goals":{"get":{"x-resource-group":"ads","operationId":"listAdConversionGoals","tags":["Conversions"],"x-platforms":["google"],"summary":"List account conversion goals","description":"Lists a Google Ads account's default conversion goals, which ones are used for bidding, and the conversion actions in each.\n\nThese are Google Ads account-default conversion goals (CustomerConversionGoal), one per category and origin. Each goal carries:\n\n- `biddable`: whether the goal is used for bidding and reported in the Conversions column.\n- The conversion actions that belong to it, each flagged `primaryForGoal` (primary) or not (secondary).\n\n### Caching\n\nReads are cached for 10 minutes. When the shared Google quota is exhausted, the last successful result is served with `stale: true`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (Google Ads)"},{"name":"adAccountId","in":"query","schema":{"type":"string","pattern":"^\\d+$"},"description":"Google customer id. Required when the connection has multiple customers."},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Alias of adAccountId"}],"responses":{"200":{"description":"Account conversion goals","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"goals":{"type":"array","items":{"$ref":"#/components/schemas/GoogleCustomerConversionGoal"}},"cachedAt":{"type":["string","null"],"format":"date-time"},"stale":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only available on Google Ads accounts"}}},"patch":{"x-resource-group":"ads","operationId":"updateAdConversionGoals","tags":["Conversions"],"x-platforms":["google"],"summary":"Update account conversion goals","description":"Turns bidding on or off for a Google Ads account's default conversion goals, which campaigns using account goals follow.\n\nSets `biddable` on one or more account-default goals, addressed by category and\norigin, in one mutate. Campaigns that use account-level goals\n(`goalConfigLevel: CUSTOMER`) follow the change. Returns the re-read goal list.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["accountId","goals"],"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id (Google Ads)"},"adAccountId":{"type":"string","pattern":"^\\d+$","description":"Google customer id. Required when the connection has multiple customers."},"customerId":{"type":"string","pattern":"^\\d+$","deprecated":true,"description":"Alias of adAccountId"},"goals":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/GoogleBiddableGoalInput"}}}}}}},"responses":{"200":{"description":"Goals updated","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"goals":{"type":"array","items":{"$ref":"#/components/schemas/GoogleCustomerConversionGoal"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only available on Google Ads accounts"}}}},"/v1/ads/conversions/actions/{actionId}":{"patch":{"x-resource-group":"ads","operationId":"updateConversionAction","tags":["Conversions"],"x-platforms":["google"],"summary":"Update a conversion action's settings","description":"Changes a Google Ads conversion action's settings, such as primary or secondary, counting, value and lookback windows, or removes or restores it.\n\nUpdates a Google Ads conversion action in one mutate, each field sent written on its own\nupdate mask leaf so omitted fields keep their value. Send at least one field.\n\n`primaryForGoal` sets `primary_for_goal`: a primary action counts toward its goal's\nbidding and the Conversions column; a secondary one is observation-only (All\nconversions). `countingType`, `category`, the value settings (`defaultValue`,\n`defaultCurrency`, `alwaysUseDefaultValue`) and the click-through / view-through\nlookback windows map to the same-named conversion_action fields.\n\n`status: REMOVED` removes the action (Google keeps it, with its history, as REMOVED) and\nmust be sent alone; `status: ENABLED` restores a removed action. Google refuses HIDDEN\non website actions, so it is not offered.","security":[{"bearerAuth":[]}],"parameters":[{"name":"actionId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Google conversion action id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["accountId"],"minProperties":2,"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id (Google Ads)"},"adAccountId":{"type":"string","pattern":"^\\d+$","description":"Google customer id. Required when the connection has multiple customers."},"customerId":{"type":"string","pattern":"^\\d+$","deprecated":true,"description":"Alias of adAccountId"},"name":{"type":"string","minLength":1,"maxLength":100},"status":{"type":"string","enum":["ENABLED","REMOVED"],"description":"REMOVED removes the action and must be sent alone; ENABLED restores a removed one."},"defaultValue":{"type":"number","minimum":0},"alwaysUseDefaultValue":{"type":"boolean"},"category":{"type":"string","enum":["DEFAULT","PAGE_VIEW","PURCHASE","SIGNUP","DOWNLOAD","ADD_TO_CART","BEGIN_CHECKOUT","SUBSCRIBE_PAID","PHONE_CALL_LEAD","IMPORTED_LEAD","SUBMIT_LEAD_FORM","BOOK_APPOINTMENT","REQUEST_QUOTE","GET_DIRECTIONS","OUTBOUND_CLICK","CONTACT","ENGAGEMENT","STORE_VISIT","STORE_SALE","QUALIFIED_LEAD","CONVERTED_LEAD"],"description":"conversion_action.category. Defaults to DEFAULT on create."},"countingType":{"type":"string","enum":["ONE_PER_CLICK","MANY_PER_CLICK"],"description":"ONE_PER_CLICK counts one conversion per ad click (leads); MANY_PER_CLICK counts every one (purchases)."},"defaultCurrency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 currency of defaultValue (value_settings.default_currency_code)."},"clickThroughLookbackWindowDays":{"type":"integer","minimum":1,"maximum":90,"description":"Days after an ad click a conversion still counts."},"viewThroughLookbackWindowDays":{"type":"integer","minimum":1,"maximum":30,"description":"Days after an ad view a view-through conversion still counts."},"primaryForGoal":{"type":"boolean","description":"true = primary (counts toward bidding when its goal is biddable), false = secondary."}}}}}},"responses":{"200":{"description":"Action updated","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"action":{"type":"object","description":"The action id with the fields written, echoed back.","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"primaryForGoal":{"type":"boolean"},"category":{"type":"string"},"countingType":{"type":"string"},"defaultValue":{"type":"number"},"defaultCurrency":{"type":"string"},"alwaysUseDefaultValue":{"type":"boolean"},"clickThroughLookbackWindowDays":{"type":"integer"},"viewThroughLookbackWindowDays":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only available on Google Ads accounts"}}}},"/v1/ads/conversions/custom-goals":{"get":{"x-resource-group":"ads","operationId":"listCustomConversionGoals","tags":["Conversions"],"x-platforms":["google"],"summary":"List custom conversion goals","description":"Lists the custom conversion goals in a Google Ads account, each a named set of conversion actions a campaign can bid on.\n\nGoogle Ads custom conversion goals (a named set of conversion actions a campaign can bid on). Removed goals are excluded. Cached like the other Google reads.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (Google Ads)"},{"name":"adAccountId","in":"query","schema":{"type":"string","pattern":"^\\d+$"},"description":"Google customer id. Required when the connection has multiple customers."},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Alias of adAccountId"}],"responses":{"200":{"description":"Custom conversion goals","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"goals":{"type":"array","items":{"$ref":"#/components/schemas/GoogleCustomConversionGoal"}},"cachedAt":{"type":["string","null"],"format":"date-time"},"stale":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only available on Google Ads accounts"}}},"post":{"x-resource-group":"ads","operationId":"createCustomConversionGoal","tags":["Conversions"],"x-platforms":["google"],"summary":"Create a custom conversion goal","description":"Creates a Google Ads custom conversion goal from a set of conversion actions, so a campaign can bid on just those.\n\nCreates a custom conversion goal from conversion action ids. Point a campaign at it with `PATCH /v1/ads/campaigns/{campaignId}/conversion-goals`.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["accountId","name","conversionActionIds"],"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id (Google Ads)"},"adAccountId":{"type":"string","pattern":"^\\d+$","description":"Google customer id. Required when the connection has multiple customers."},"customerId":{"type":"string","pattern":"^\\d+$","deprecated":true,"description":"Alias of adAccountId"},"name":{"type":"string","minLength":1,"maxLength":255},"conversionActionIds":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","pattern":"^\\d+$"}}}}}}},"responses":{"201":{"description":"Custom goal created","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"id":{"type":"string"},"resourceName":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only available on Google Ads accounts"}}}},"/v1/ads/conversions/custom-goals/{goalId}":{"patch":{"x-resource-group":"ads","operationId":"updateCustomConversionGoal","tags":["Conversions"],"x-platforms":["google"],"summary":"Update a custom conversion goal","description":"Renames a Google Ads custom conversion goal or replaces the conversion actions in it.\n\nReturns the re-read goal.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"goalId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Google custom conversion goal id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["accountId"],"minProperties":2,"properties":{"accountId":{"type":"string","description":"Zernio SocialAccount id (Google Ads)"},"adAccountId":{"type":"string","pattern":"^\\d+$","description":"Google customer id. Required when the connection has multiple customers."},"customerId":{"type":"string","pattern":"^\\d+$","deprecated":true,"description":"Alias of adAccountId"},"name":{"type":"string","minLength":1,"maxLength":255},"conversionActionIds":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","pattern":"^\\d+$"},"description":"Replaces the whole set."}}}}}},"responses":{"200":{"description":"Custom goal updated","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"goal":{"$ref":"#/components/schemas/GoogleCustomConversionGoal"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"description":"Goal not found on this customer, or account unavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only available on Google Ads accounts"}}},"delete":{"x-resource-group":"ads","operationId":"removeCustomConversionGoal","tags":["Conversions"],"x-platforms":["google"],"summary":"Remove a custom conversion goal","description":"Deletes a Google Ads custom conversion goal; switch any campaigns using it to another goal first.\n\nGoogle refuses (400) while any campaign still uses it: switch those campaigns to another goal first.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"goalId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Google custom conversion goal id"},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Zernio SocialAccount id (Google Ads)"},{"name":"adAccountId","in":"query","schema":{"type":"string","pattern":"^\\d+$"},"description":"Google customer id. Required when the connection has multiple customers."},{"name":"customerId","in":"query","deprecated":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Alias of adAccountId"}],"responses":{"200":{"description":"Custom goal removed","content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"goalId":{"type":"string"},"removed":{"type":"boolean","description":"Always true on success"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"description":"Goal not found on this customer, or account unavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"Only available on Google Ads accounts"}}}},"/v1/events":{"get":{"x-resource-group":"ads","operationId":"listEvents","tags":["Conversions"],"summary":"List stored events","description":"Lists the conversion events stored for a profile by `POST /v1/events`, newest first. Personal data is never\nreturned: `hasEmail`, `hasPhone` and `hasExternalId` only say whether the event carried that identifier.\nEvents sent with `testCode` are not stored, so they never appear here.\n\nPaginate with `cursor`: pass the `nextCursor` of the previous page until it comes back `null`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"profileId","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"from","in":"query","required":false,"description":"Only events at or after this time (ISO 8601, on the event time).","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"description":"Only events before this time (ISO 8601, on the event time).","schema":{"type":"string","format":"date-time"}},{"name":"eventName","in":"query","required":false,"description":"Only events with this name, such as `Purchase`.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"`nextCursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of stored events.","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"eventId":{"type":"string"},"eventName":{"type":"string"},"eventTime":{"type":"string","format":"date-time"},"receivedAt":{"type":"string","format":"date-time"},"actionSource":{"type":["string","null"]},"value":{"type":["number","null"]},"currency":{"type":["string","null"]},"sourceUrl":{"type":["string","null"],"description":"Origin, path and attribution parameters only."},"utm":{"type":"object","properties":{"source":{"type":["string","null"]},"medium":{"type":["string","null"]},"campaign":{"type":["string","null"]},"content":{"type":["string","null"]}}},"zrn":{"type":["string","null"],"description":"Ad ID from the `zrn` parameter Zernio adds to links of ads it creates."},"clickIds":{"type":"object","properties":{"gclid":{"type":["string","null"]},"fbc":{"type":["string","null"]}}},"destinationsSent":{"type":"integer","description":"Destinations the event was forwarded to."},"hasEmail":{"type":"boolean"},"hasPhone":{"type":"boolean"},"hasExternalId":{"type":"boolean"},"ad":{"type":["object","null"],"description":"The ad behind the event, when Zernio can name it. Google: from the click behind `clickIds.gclid` (synced daily from Google Ads click_view for clicks up to 14 days before the event; gbraid/wbraid clicks are not resolved). Meta: from the `zrn` ad id, for Meta ads Zernio holds. `null` otherwise.","properties":{"platform":{"type":"string","enum":["googleads","metaads"]},"customerId":{"type":"string","description":"Google Ads customer id (Google only)."},"campaignId":{"type":["string","null"]},"adGroupId":{"type":["string","null"],"description":"Google only."},"adSetId":{"type":["string","null"],"description":"Meta only."},"adId":{"type":["string","null"]}}}}}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; `null` on the last page."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"x-resource-group":"ads","operationId":"sendEvents","tags":["Conversions"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","reddit"],"summary":"Send events to every destination","description":"Sends conversion events once and forwards them to every ad platform destination saved for the profile (see `POST /v1/events/destinations`), or to the `destinations` given in the request. Requires the Ads add-on.\n\n### Forwarding\n\n- Each destination receives the events exactly as `POST /v1/ads/conversions` would send them, so the per-platform notes there (hashing, batching, `eventName` semantics, dedup on `eventId`) apply here too.\n- A destination saved with `eventNames` only receives events with those names.\n- One destination failing never blocks the others: each one reports its own result.\n\n### Storage\n\nZernio also stores each event for the profile's reporting.\n\n- Email, phone and `externalId` are stored only as SHA-256 hashes.\n- `sourceUrl` keeps only its origin, path and attribution parameters (`utm_*`, `gclid`, `fbclid`, `ttclid`, `li_fat_id`, `epik`, `rdt_cid`, `gbraid`, `wbraid`).\n- Events sent with `testCode` are forwarded but not stored.\n- Sending an event again with the same `eventId` replaces the stored one.\n- A stored `Purchase`, `Lead` or `QualifiedLead` tied to one of your campaigns (see `campaign` on each event) counts in `GET /v1/ads/campaign-results` and in ad rules as `sales` and `revenue`, `leads` or `qualified_leads`.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","events"],"additionalProperties":false,"properties":{"profileId":{"type":"string","description":"Profile the events belong to. Its saved destinations receive the events."},"events":{"type":"array","minItems":1,"maxItems":1000,"items":{"$ref":"#/components/schemas/ConversionEvent"}},"destinations":{"type":"array","minItems":1,"maxItems":20,"description":"Send to these destinations instead of the saved ones (every event goes to each).","items":{"type":"object","required":["accountId","destinationId"],"additionalProperties":false,"properties":{"accountId":{"type":"string","description":"Connected ads account ID (metaads, googleads, linkedinads, tiktokads, openaiads, pinterestads or redditads)."},"destinationId":{"type":"string","description":"Platform destination, as listed by GET /v1/accounts/{accountId}/conversion-destinations."}}}},"consent":{"type":"object","description":"Batch-level user consent, forwarded to every destination (see POST /v1/ads/conversions).","properties":{"adUserData":{"type":"string","enum":["GRANTED","DENIED"]},"adPersonalization":{"type":"string","enum":["GRANTED","DENIED"]}}},"testCode":{"type":"string","description":"Forwarded as each platform test code (see POST /v1/ads/conversions). A root-level `test_event_code` is accepted as an alias. Test events are not stored."}}}}}},"responses":{"200":{"x-summary":"The events were processed: check each destination for partial failure.","description":"Events processed. Check each destination for partial failure.","content":{"application/json":{"schema":{"type":"object","properties":{"eventsReceived":{"type":"integer","description":"Events in the request."},"stored":{"type":"boolean","description":"Whether the events were stored for reporting (always false with testCode)."},"testCode":{"type":["string","null"],"description":"The test code forwarded to every destination, or `null` when the request carried none."},"destinations":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string"},"destinationId":{"type":"string"},"platform":{"type":"string","enum":["metaads","googleads","linkedinads","tiktokads","openaiads","pinterestads","redditads"]},"eventsSent":{"type":"integer","description":"Events the platform accepted."},"eventsFailed":{"type":"integer"},"failures":{"type":"array","items":{"type":"object","properties":{"eventIndex":{"type":"integer","description":"Index into the events sent to this destination."},"eventId":{"type":"string"},"message":{"type":"string"},"code":{"oneOf":[{"type":"string"},{"type":"integer"}]}}}},"error":{"type":"string","description":"Set when the destination could not be reached at all (account disconnected, unsupported platform, platform error)."}}}}}}}}},"400":{"x-summary":"The body is invalid, for example `test_event_code` is empty or conflicts with the test code: fix it and resend.","description":"Invalid body, including a `test_event_code` that is not a non-empty string, or `testCode` and `test_event_code` with different values (`param: test_event_code`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/events/destinations":{"get":{"x-resource-group":"ads","operationId":"listEventDestinations","tags":["Conversions"],"summary":"List event destinations","description":"Lists the ad platform destinations that receive events sent to `POST /v1/events`, for one profile or every profile you can access.","security":[{"bearerAuth":[]}],"parameters":[{"name":"profileId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Event destinations.","content":{"application/json":{"schema":{"type":"object","properties":{"destinations":{"type":"array","items":{"$ref":"#/components/schemas/EventDestination"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"x-resource-group":"ads","operationId":"createEventDestination","tags":["Conversions"],"summary":"Add an event destination","description":"Saves an ad platform destination for a profile, so events sent to `POST /v1/events` for that profile are forwarded\nto it. Pick `destinationId` from `GET /v1/accounts/{accountId}/conversion-destinations`. Set `eventNames` to forward\nonly those events (for example only `Purchase`); leave it out to forward every event.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId","accountId","destinationId"],"additionalProperties":false,"properties":{"profileId":{"type":"string"},"accountId":{"type":"string","description":"Connected ads account ID that owns the destination."},"destinationId":{"type":"string"},"eventNames":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Destination saved.","content":{"application/json":{"schema":{"type":"object","properties":{"destination":{"$ref":"#/components/schemas/EventDestination"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The profile already sends events to this destination (code `invalid_resource_state`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/events/destinations/{destinationId}":{"delete":{"x-resource-group":"ads","operationId":"deleteEventDestination","tags":["Conversions"],"summary":"Remove an event destination","description":"Stops forwarding events to this destination. `destinationId` is the event destination `id`, not the platform destination.","security":[{"bearerAuth":[]}],"parameters":[{"name":"destinationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Destination removed.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/ads/campaigns/{campaignId}/conversion-goals":{"get":{"x-resource-group":"ads","operationId":"getCampaignConversionGoals","tags":["Ad Campaigns"],"x-platforms":["google"],"summary":"Get campaign conversion goals","description":"Shows which conversion goals a Google campaign bids on, and whether it follows the account defaults or uses its own or a custom goal.\n\nA Google campaign's conversion goals (CampaignConversionGoal, `biddable` per category\nand origin) and its goal config (ConversionGoalCampaignConfig): `goalConfigLevel`\nCUSTOMER means the campaign follows the account-default goals, CAMPAIGN means it uses\nits own goals or `customConversionGoalId`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Google campaign id"}],"responses":{"200":{"description":"Campaign conversion goals","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GoogleCampaignConversionGoals"},{"type":"object","properties":{"customerId":{"type":"string"},"cachedAt":{"type":["string","null"],"format":"date-time"},"stale":{"type":"boolean"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"description":"Campaign not found"},"409":{"description":"Campaign matches multiple accessible accounts, or the connection needs reconnecting"},"501":{"description":"Only available on Google Ads campaigns"}}},"patch":{"x-resource-group":"ads","operationId":"updateCampaignConversionGoals","tags":["Ad Campaigns"],"x-platforms":["google"],"summary":"Update campaign conversion goals","description":"Changes which conversions a Google campaign bids on, switching between account-default goals, its own goals or a custom goal.\n\nIn one mutate, it can:\n\n- set `biddable` on campaign goals\n- switch `goalConfigLevel`\n- point the campaign at a custom conversion goal\n\n`customConversionGoalId: null` clears it. Google refuses that (400) while the campaign stays at CAMPAIGN level with no biddable goals, so send `goalConfigLevel: CUSTOMER` with it to fall back to the account goals.\n\nReturns the re-read campaign goals.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Google campaign id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"goals":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/GoogleBiddableGoalInput"}},"goalConfigLevel":{"type":"string","enum":["CUSTOMER","CAMPAIGN"]},"customConversionGoalId":{"type":["string","null"],"pattern":"^\\d+$","description":"Custom goal to bid on, or null to clear"}}}}}},"responses":{"200":{"description":"Campaign goals updated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GoogleCampaignConversionGoals"},{"type":"object","properties":{"customerId":{"type":"string"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AdAccountNotSelected"},"404":{"description":"Campaign not found"},"409":{"description":"Campaign matches multiple accessible accounts, or the connection needs reconnecting"},"501":{"description":"Only available on Google Ads campaigns"}}}},"/v1/accounts/{accountId}/conversion-destinations":{"get":{"x-resource-group":"ads","operationId":"listConversionDestinations","tags":["Conversions"],"x-platforms":["meta","google","tiktok","linkedin","pinterest","reddit"],"summary":"List conversion destinations","description":"Lists where an ad account can receive conversion events (pixels, conversion actions or rules), so you know where to send them.\n\nReturns the list of pixels (Meta), conversion actions (Google),\nconversion rules (LinkedIn), pixels (OpenAI Ads, Reddit) or ad accounts\n(Pinterest) accessible to the connected ads account. Use the returned `id` as `destinationId` when\nposting to `POST /v1/ads/conversions`.\n\nFor Google and LinkedIn, each destination's `type` reflects the\nconversion type (PURCHASE, LEAD, SIGN_UP, etc.), and the event type is\nlocked to the destination. For Meta, OpenAI Ads and Reddit, `type` is absent:\npixels accept any event name per request.\n\nFor Reddit, the pixels of every ad account the connection reaches (only the scoped\nones when the connection has an ad-account scope), each with the `adAccountId` that owns\nit. Reddit pixels are created in Reddit Ads Manager, not through Zernio.\n\nFor LinkedIn, destinations are returned across every sponsored ad\naccount the connected token can access; the `adAccountId` field on\neach destination identifies the parent ad account and is required for\nsubsequent CRUD calls (update, delete, associations, metrics).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"SocialAccount ID (metaads, googleads, linkedinads, tiktokads, openaiads, pinterestads, or redditads)."}],"responses":{"200":{"description":"Destinations listed","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["metaads","googleads","linkedinads","tiktokads","openaiads","pinterestads","redditads"]},"destinations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Destination identifier. Meta: pixel ID. Google:\nconversion action resource name. LinkedIn:\nnumeric conversion rule ID. OpenAI Ads: pixel wire\nid. Reddit: pixel id (`a2_...`).\n"},"name":{"type":"string"},"type":{"type":"string","description":"Present when the platform locks event type to the\ndestination (Google conversion actions, LinkedIn\nconversion rules).\n"},"status":{"type":"string","enum":["active","inactive"]},"adAccountId":{"type":"string","description":"Set by adapters whose destinations are scoped to a\nspecific ad account (LinkedIn, Reddit). On LinkedIn,\npass it back on subsequent CRUD calls.\n"},"conversionEvents":{"type":"array","description":"OpenAI Ads only: the conversion event settings wired\nto this pixel. Pass one's `id`, `eventType` or `name`\nas `promotedObject.customEventType` on a\n`goal: conversions` create (POST /v1/ads/create or\nPOST /v1/ads/campaigns) to optimize for it. Without\nit, the account's most recently created `optimizable`\nevent is used; when none is, the create returns 400.\n","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"eventType":{"type":["string","null"],"description":"OpenAI event type, e.g. order_created, lead_created, or custom."},"customEventName":{"type":["string","null"]},"archived":{"type":"boolean"},"optimizable":{"type":"boolean","description":"Active and standard (not custom). Only these can be a conversions campaign's optimization event."}}}}}}}}}}}},"400":{"description":"Account's platform is not supported by the Conversions API."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the LinkedIn account lacks the conversions scope: enable Ads access or reconnect the account.","description":"Ads access required (Ads add-on on legacy plans, included on usage-based plans),\nOR (for LinkedIn) the connected account lacks the `rw_conversions` scope and must be reconnected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"x-summary":"The LinkedIn rate limit was reached: retry later with backoff.","description":"LinkedIn rate limit hit. Retry with backoff."}}},"post":{"x-resource-group":"ads","operationId":"createConversionDestination","tags":["Conversions"],"x-platforms":["google","linkedin"],"summary":"Create a conversion destination","description":"Creates a new place to send conversion events: a Google Ads conversion action or a LinkedIn conversion rule.\n\nSupported for LinkedIn (conversion rule) and Google Ads (conversion action). It returns 405 for:\n\n- Meta and OpenAI Ads: their pixels are created via their own tracking-tags flow instead (`POST /v1/accounts/{accountId}/tracking-tags`)\n- Reddit: create Reddit pixels in Reddit Ads Manager\n\n### LinkedIn\n\nCreation is NOT idempotent. A retry creates a second destination. Deduplicate before retrying.\n\nThe rule is created with `conversionMethod=CONVERSIONS_API` and (by default) auto-associated with all of the ad account's campaigns via `autoAssociationType=ALL_CAMPAIGNS`. Pass `autoAssociationType: NONE` to opt out and manage associations explicitly via the associations endpoints below.\n\n365-day attribution windows are only valid for these rule types; the API rejects other combinations locally:\n\n- `SUBMIT_APPLICATION`\n- `PURCHASE`\n- `ADD_TO_CART`\n- `QUALIFIED_LEAD`\n- `LEAD`\n\n### Google Ads\n\nCalling with a name that already exists reuses the existing conversion action transparently (the response is identical to a fresh create). Calling with the same name but a different category returns a typed `IDEMPOTENCY_CONFLICT` (409) rather than silently returning the mismatched action.\n\nThe conversion action is created with `type=UPLOAD_CLICKS` (required for API-uploaded offline conversions, immutable after creation).\n\nThe `type` field carries the Google `ConversionActionCategory` enum value, e.g. `PURCHASE`, `SUBSCRIBE_PAID`, `SIGNUP`, `IMPORTED_LEAD`, `BOOK_APPOINTMENT`. Unified standard event names (e.g. `Purchase`, `Subscribe`, `CompleteRegistration`, `Lead`, `Schedule`) are resolved to their Google category equivalents automatically.\n\nThe action defaults to secondary (non-primary) to avoid immediately steering Smart Bidding; pass `primaryForGoal: true` to opt in.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"SocialAccount ID (linkedinads or googleads)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["adAccountId","name","type"],"properties":{"adAccountId":{"type":"string","description":"Ad account ID. For LinkedIn: numeric (e.g. \"5123456\") or\nfull `urn:li:sponsoredAccount:{id}` URN. For Google: numeric\ncustomer ID (e.g. \"1234567890\") or `customers/{id}` form.\n"},"name":{"type":"string","maxLength":255},"type":{"type":"string","description":"Conversion type. Unknown values pass through to the platform.\n\n- LinkedIn: a unified standard event name (e.g. \"Purchase\", \"Lead\", \"AddToCart\") or a LinkedIn rule type enum (e.g. \"PURCHASE\", \"QUALIFIED_LEAD\").\n- Google: a unified standard event name (Purchase, Subscribe, CompleteRegistration, Lead, Schedule) or a Google ConversionActionCategory enum value directly (e.g. \"PURCHASE\", \"SUBSCRIBE_PAID\", \"SIGNUP\", \"IMPORTED_LEAD\", \"BOOK_APPOINTMENT\").\n"},"attributionType":{"type":"string","enum":["LAST_TOUCH_BY_CAMPAIGN","LAST_TOUCH_BY_CONVERSION"],"description":"LinkedIn only."},"postClickAttributionWindowSize":{"type":"integer","enum":[1,7,30,90,365],"description":"LinkedIn only. Default 30. 365 only allowed for LEAD,\nPURCHASE, ADD_TO_CART, QUALIFIED_LEAD, SUBMIT_APPLICATION\nrule types; the API rejects other combinations locally.\n"},"viewThroughAttributionWindowSize":{"type":"integer","enum":[1,7,30,90,365],"description":"LinkedIn only. Default 7. Same 365-day-window type\nrestriction applies as `postClickAttributionWindowSize`.\n"},"valueType":{"type":"string","enum":["DYNAMIC","FIXED","NO_VALUE"],"description":"LinkedIn only. DYNAMIC (default) uses the per-event `value`\nfrom `sendConversions`. FIXED uses the rule's `value` field.\nNO_VALUE drops monetary value entirely.\n"},"value":{"type":"object","required":["currencyCode","amount"],"description":"LinkedIn only. Static conversion value. Used when\n`valueType=FIXED`. The currency should match the ad\naccount's currency.\n","properties":{"currencyCode":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 (e.g. \"USD\")."},"amount":{"type":"string","description":"Decimal string (e.g. \"49.99\")."}}},"autoAssociationType":{"type":"string","enum":["ALL_CAMPAIGNS","OBJECTIVE_BASED","NONE"],"default":"ALL_CAMPAIGNS","description":"LinkedIn only. Controls campaign association at rule-creation time:\n\n- ALL_CAMPAIGNS: associate the rule with every active, paused, and draft campaign in the ad account.\n- OBJECTIVE_BASED: associate only campaigns whose objective matches the rule's type.\n- NONE: don't auto-associate. Manage associations via the `/associations` endpoints below.\n\nAuto-association runs once at create time; campaigns added after the rule still need explicit association.\n"},"countingType":{"type":"string","enum":["MANY_PER_CLICK","ONE_PER_CLICK"],"description":"Google Ads only. Whether to count multiple conversions from\nthe same click (MANY_PER_CLICK) or at most one\n(ONE_PER_CLICK). Defaults to MANY_PER_CLICK if omitted.\n"},"primaryForGoal":{"type":"boolean","description":"Google Ads only. When true, the conversion action is marked\nas primary and immediately influences Smart Bidding. Defaults\nto false (secondary, record-only) to avoid unintentionally\nsteering the customer's campaigns on creation.\n"}}}}}},"responses":{"201":{"description":"Destination created","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["linkedinads","googleads"]},"destination":{"$ref":"#/components/schemas/ConversionDestination"}}}}}},"400":{"description":"Invalid body or platform validation failure."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access or the LinkedIn conversions scope is missing, or the ad account is not selected: fix access or reconnect the account.","description":"Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the connected LinkedIn account lacks the `rw_conversions` scope (reconnect required).\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"405":{"description":"Platform does not support destination creation."},"409":{"x-summary":"A conversion action with this name already exists, or the account needs reconnection: use another name or reconnect the account.","description":"Conflict. One of:\n\n- `IDEMPOTENCY_CONFLICT` (Google Ads only): a conversion action with the given name already exists but has a different category. Use a different name or the existing destination.\n- ads_connection_required: the account is inactive or needs reconnection. Reconnect it and read GET /v1/accounts for its current ID before retrying.\n"},"422":{"x-summary":"No Google Ads client account is usable on this connection: reconnect with a user who reaches one, or create one first.","description":"Google Ads connection not usable.\n\n- Code `ads_connection_required`: no Google Ads customer account is left on this connection after its ad-account selection. Reconnect via GET /v1/connect/googleads/ads with a Google user that can reach the ad account, or select one of its ad accounts.\n- Code `invalid_resource_state`: the connection reaches only a Google Ads manager account with no client accounts yet. Create one with POST /v1/ads/accounts or under the manager in Google Ads, then retry.\n"},"429":{"x-summary":"The rate limit was reached: retry later with backoff.","description":"Rate limit hit. Retry with backoff."}}}},"/v1/accounts/{accountId}/conversion-destinations/{destinationId}":{"get":{"x-resource-group":"ads","operationId":"getConversionDestination","tags":["Conversions"],"x-platforms":["linkedin"],"summary":"Get a conversion destination","description":"Shows one LinkedIn conversion rule with its full settings.\n\nLinkedIn-only today. Returns the full destination record for one\nconversion rule. The `adAccountId` query parameter is required because\nLinkedIn rules are scoped to a sponsored ad account.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"destinationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"Numeric ID or full `urn:li:sponsoredAccount:{id}` URN."}],"responses":{"200":{"description":"Destination fetched","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["linkedinads"]},"destination":{"$ref":"#/components/schemas/ConversionDestination"}}}}}},"400":{"description":"Validation error."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads add-on or LinkedIn reconnect required."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"405":{"description":"Platform does not support fetching a single destination."},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"x-summary":"The LinkedIn rate limit was reached: retry later with backoff.","description":"LinkedIn rate limit hit. Retry with backoff."}}},"patch":{"x-resource-group":"ads","operationId":"updateConversionDestination","tags":["Conversions"],"x-platforms":["linkedin"],"summary":"Update a conversion destination","description":"Changes a LinkedIn conversion rule's name, value, attribution windows, or turns it on or off.\n\nPartial-update a conversion rule. LinkedIn-only today. Whitelisted\nfields: `name`, `enabled`, attribution windows, `valueType`, `value`,\n`attributionType`. The rule's `type` and parent ad account are\nintentionally not exposed for update. Recreate the rule if those\nneed to change.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"destinationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["adAccountId"],"description":"At least one mutable field beyond `adAccountId` is required;\nthe route returns 400 if no patch fields are provided.\n","properties":{"adAccountId":{"type":"string"},"name":{"type":"string","maxLength":255},"enabled":{"type":"boolean","description":"Setting `false` is equivalent to calling DELETE: the\nrule will appear as `inactive` afterwards.\n"},"attributionType":{"type":"string","enum":["LAST_TOUCH_BY_CAMPAIGN","LAST_TOUCH_BY_CONVERSION"]},"postClickAttributionWindowSize":{"type":"integer","enum":[1,7,30,90,365],"description":"365 only allowed for LEAD, PURCHASE, ADD_TO_CART,\nQUALIFIED_LEAD, SUBMIT_APPLICATION rule types.\n"},"viewThroughAttributionWindowSize":{"type":"integer","enum":[1,7,30,90,365],"description":"365 only allowed for LEAD, PURCHASE, ADD_TO_CART,\nQUALIFIED_LEAD, SUBMIT_APPLICATION rule types.\n"},"valueType":{"type":"string","enum":["DYNAMIC","FIXED","NO_VALUE"]},"value":{"type":"object","description":"Used when `valueType=FIXED`.","properties":{"currencyCode":{"type":"string","description":"ISO 4217."},"amount":{"type":"string","description":"Decimal string (e.g. \"49.99\")."}}}}}}}},"responses":{"200":{"description":"Destination updated (re-fetched canonical state)","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["linkedinads"]},"destination":{"$ref":"#/components/schemas/ConversionDestination"}}}}}},"400":{"description":"Invalid body or LinkedIn validation failure."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The Ads add-on, LinkedIn reconnection or ad account selection is missing: enable the add-on, reconnect LinkedIn, or select the ad account.","description":"Ads add-on or LinkedIn reconnect required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection), or use a connection that has it selected."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"405":{"description":"Platform does not support updating destinations."},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"x-summary":"The LinkedIn rate limit was reached: retry later with backoff.","description":"LinkedIn rate limit hit. Retry with backoff."}}},"delete":{"x-resource-group":"ads","operationId":"deleteConversionDestination","tags":["Conversions"],"x-platforms":["linkedin"],"summary":"Delete a conversion destination","description":"Disables a LinkedIn conversion rule, which is how LinkedIn deletes it; the rule can still be read afterwards.\n\nLinkedIn-only today. LinkedIn does not expose hard-delete on conversion\nrules; what their UI calls \"delete\" is the same `enabled: false` flip\nwe apply here. The rule remains fetchable via GET with\n`status: 'inactive'`; the unified discovery endpoint hides it by\ndefault.\n\n`adAccountId` may be passed as a query parameter (recommended) or as\na JSON body field for clients that can send DELETE bodies.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"destinationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"Required as query OR in JSON body."}],"responses":{"204":{"description":"Soft-deleted."},"400":{"description":"adAccountId missing, or accountId is not a valid id."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The Ads add-on, LinkedIn reconnection or ad account selection is missing: enable the add-on, reconnect LinkedIn, or select the ad account.","description":"Ads add-on or LinkedIn reconnect required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix it, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"405":{"description":"Platform does not support deleting destinations."},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"x-summary":"The LinkedIn rate limit was reached: retry later with backoff.","description":"LinkedIn rate limit hit. Retry with backoff."}}}},"/v1/accounts/{accountId}/conversion-destinations/{destinationId}/associations":{"get":{"x-resource-group":"ads","operationId":"listConversionAssociations","tags":["Conversions"],"x-platforms":["linkedin"],"summary":"List associated campaigns","description":"Lists the LinkedIn campaigns that track a conversion rule, so you can spot newer campaigns that still need linking.\n\nLinkedIn-only today. Returns the campaigns currently associated with\nthis conversion rule. Auto-association on rule creation\nruns once at create time; campaigns created after the rule still need\nexplicit association.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"destinationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Associations listed","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["linkedinads"]},"associations":{"type":"array","items":{"type":"object","properties":{"campaignId":{"type":"string"},"conversionId":{"type":"string"},"associatedAt":{"type":"integer","description":"Epoch ms."}}}}}}}}},"400":{"description":"Validation error."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads add-on or LinkedIn reconnect required."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"405":{"description":"Platform does not support associations."},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"x-summary":"The LinkedIn rate limit was reached: retry later with backoff.","description":"LinkedIn rate limit hit. Retry with backoff."}}},"post":{"x-resource-group":"ads","operationId":"addConversionAssociations","tags":["Conversions"],"x-platforms":["linkedin"],"summary":"Associate campaigns","description":"Links campaigns to a LinkedIn conversion rule so they track it, reporting which links succeeded or failed.\n\nReturns a\nper-campaign success/failure result so callers can retry only the\nrows that failed (e.g. wrong campaign type for the rule's objective).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"destinationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["adAccountId","campaignIds"],"properties":{"adAccountId":{"type":"string"},"campaignIds":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","description":"Numeric campaign ID or full `urn:li:sponsoredCampaign:{id}` URN."}}}}}}},"responses":{"200":{"x-summary":"The batch ran per campaign and returned 200 even if some rows failed: inspect `failed` for the rejected rows.","description":"Per-campaign batch result. Status is 200 even when some rows\nfailed. Inspect `failed[]` for details. Inputs that fail local\nURN validation are bucketed into `failed` without ever hitting\nLinkedIn.\n","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["linkedinads"]},"succeeded":{"type":"array","description":"Numeric campaign IDs that were successfully associated.","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"campaignId":{"type":"string"},"reason":{"type":"string"}}}}}}}}},"400":{"description":"Invalid body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The Ads add-on, LinkedIn reconnection or ad account selection is missing: enable the add-on, reconnect LinkedIn, or select the ad account.","description":"Ads add-on or LinkedIn reconnect required.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"405":{"description":"Platform does not support associations."},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"x-summary":"The LinkedIn rate limit was reached: retry later with backoff.","description":"LinkedIn rate limit hit. Retry with backoff."}}},"delete":{"x-resource-group":"ads","operationId":"removeConversionAssociations","tags":["Conversions"],"x-platforms":["linkedin"],"summary":"Remove associated campaigns","description":"Unlinks campaigns from a LinkedIn conversion rule so they stop tracking it.\n\nPass `adAccountId` and `campaignIds` as query parameters (`campaignIds` is comma-separated).\n\nThe route also accepts a JSON body with the same fields, for clients that prefer DELETE-with-body. The documented surface is query-only because some SDK code generators (e.g. Python) collapse query + body parameters with the same name into a single kwarg.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"destinationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"campaignIds","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated list of campaign IDs."}],"responses":{"200":{"x-summary":"The batch ran per campaign and returned 200 even if some rows failed: inspect `failed` for the rejected rows.","description":"Per-campaign batch result. Status is 200 even when some rows\nfailed. Inspect `failed[]` for details.\n","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["linkedinads"]},"succeeded":{"type":"array","description":"Numeric campaign IDs that were successfully removed.","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"campaignId":{"type":"string"},"reason":{"type":"string"}}}}}}}}},"400":{"x-summary":"The request is invalid: send an ad account ID and up to 100 `campaignIds`, with a valid account ID.","description":"Validation error: missing `adAccountId` or `campaignIds`,\ncampaignIds exceeds 100 entries per request, or `accountId` is not\na valid id.\n"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The Ads add-on, LinkedIn reconnection or ad account selection is missing: enable the add-on, reconnect LinkedIn, or select the ad account.","description":"Forbidden. One of:\n\n- Ads add-on or LinkedIn reconnect required.\n- Code `ad_account_not_selected`: the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"405":{"description":"Platform does not support associations."},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"x-summary":"The LinkedIn rate limit was reached: retry later with backoff.","description":"LinkedIn rate limit hit. Retry with backoff."}}}},"/v1/accounts/{accountId}/conversion-destinations/{destinationId}/metrics":{"get":{"x-resource-group":"ads","operationId":"getConversionMetrics","tags":["Conversions"],"x-platforms":["linkedin"],"summary":"Get attribution metrics","description":"Shows a LinkedIn conversion rule's attributed conversions, value, leads and cost over time.\n\nLinkedIn-only today. Returns conversion-attribution metrics\n(`externalWebsiteConversions`, `externalWebsitePostClickConversions`,\n`externalWebsitePostViewConversions`, `conversionValueInLocalCurrency`,\n`qualifiedLeads`, `costInLocalCurrency`) bucketed by date.\n\nDate-range constraints (passed through from LinkedIn):\n- `granularity=DAILY` is retained for ~6 months only\n- `granularity=ALL` with a range > 6 months auto-rounds to month boundaries\n- `granularity=MONTHLY`/`YEARLY` retains 24 months\n\nThrottle: LinkedIn caps adAnalytics at 45M metric values per 5-minute\nwindow across the calling token. Single-rule queries are well within\nthat limit; surfaces as 429 if hit.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"destinationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"}},{"name":"startDate","in":"query","required":true,"schema":{"type":"string","pattern":"^\\\\d{4}-\\\\d{2}-\\\\d{2}$"}},{"name":"endDate","in":"query","schema":{"type":"string","pattern":"^\\\\d{4}-\\\\d{2}-\\\\d{2}$"}},{"name":"granularity","in":"query","schema":{"type":"string","enum":["ALL","DAILY","MONTHLY","YEARLY"],"default":"DAILY"}}],"responses":{"200":{"description":"Metrics rows","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["linkedinads"]},"granularity":{"type":"string","enum":["ALL","DAILY","MONTHLY","YEARLY"]},"rows":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","description":"YYYY-MM-DD"},"end":{"type":"string","description":"YYYY-MM-DD (inclusive)"},"metrics":{"type":"object","additionalProperties":{"oneOf":[{"type":"number"},{"type":"string"}]}}}}}}}}}},"400":{"description":"Validation error or invalid date range."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads add-on or LinkedIn reconnect required."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"405":{"description":"Platform does not support metrics readback."},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"description":"LinkedIn analytics rate limit hit."}}}},"/v1/whatsapp/conversions":{"get":{"x-resource-group":"ads","operationId":"listWhatsAppConversions","tags":["WhatsApp"],"summary":"List conversion events","description":"Returns the most recent conversion events sent through `POST /v1/whatsapp/conversions` for the given WhatsApp account.\n\nIt is sourced from delivery logs (Axiom `late` dataset), so the visible window is bounded by log retention (about 30 days). Useful for rendering a \"recent activity\" panel on the conversions setup tab without standing up a parallel persistence layer.\n\n### Per-event payload\n\nIt mirrors the structured log we write on every successful send:\n\n- `eventName`\n- `conversationId`\n- `eventsReceived`\n- `eventsFailed`\n- `traceId`\n- `durationMs`\n- the wall-clock `timestamp`\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"WhatsApp account ID"},{"name":"limit","in":"query","required":false,"description":"Max events to return (1-200, default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Recent conversion events","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time","description":"When the event was sent to Meta."},"eventName":{"type":"string","description":"One of LeadSubmitted, QualifiedLead, Purchase, AddToCart, InitiateCheckout, ViewContent, OrderCreated, OrderCanceled, OrderReturned."},"conversationId":{"type":["string","null"]},"eventsReceived":{"type":["integer","null"],"description":"Number of events Meta accepted on this send (usually 1)."},"eventsFailed":{"type":["integer","null"],"description":"Number of events Meta rejected (usually 0)."},"traceId":{"type":["string","null"],"description":"Meta fbtrace_id for cross-referencing in Events Manager."},"durationMs":{"type":["integer","null"]}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"WhatsApp account not found"}}},"post":{"x-resource-group":"ads","operationId":"sendWhatsAppConversion","tags":["WhatsApp"],"summary":"Send WhatsApp conversion event","description":"Forward a WhatsApp Business Messaging conversion event to Meta's Conversions API with `action_source = business_messaging` and `messaging_channel = whatsapp`.\n\nSupported events:\n\n- `LeadSubmitted`\n- `QualifiedLead`\n- `Purchase`\n- `AddToCart`\n- `InitiateCheckout`\n- `ViewContent`\n- `OrderCreated`\n- `OrderCanceled`\n- `OrderReturned`\n\nThe endpoint looks up the originating CTWA click ID (`ctwa_clid`) captured on the first inbound message of the conversation. It replays it on every event so Meta can attribute the conversion back to the Click-to-WhatsApp ad that drove the chat.\n\n### Configuration prerequisite\n\nOn the WhatsApp account metadata:\n\n- `metaCapiDatasetId`: the Meta dataset ID linked to the WABA. Provision one with `POST /v1/whatsapp/dataset`.\n\nThe WABA ID (already set automatically at connect time) is forwarded as `user_data.whatsapp_business_account_id`, the per-channel attribution identifier Meta requires for WhatsApp events. No Facebook Page ID is needed (that field is the Messenger-branch identifier).\n\n### Identifying the conversation\n\nIdentify the conversation by either `conversationId` (preferred) or `phoneE164` (digits only, no `+`). At least one is required.\n\nIf the conversation has no captured `ctwa_clid`, the request returns 422 because there is nothing to attribute.\n\n### Token and dataset coupling\n\nThe WhatsApp account's accessToken must have access to the configured `metaCapiDatasetId`. By default a WABA's system-user token is scoped to the WABA's own Business Manager and cannot post to a pixel owned by a different Business; Meta returns code 100 in that case.\n\nTo fix it, either:\n\n- share the dataset with the WhatsApp app's Business in BM, or\n- use a dataset already in the same Business as the WABA.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","eventName","eventId"],"description":"In addition to the `required` list, at least one of\n`conversationId` or `phoneE164` must be supplied (used to\nresolve the originating CTWA conversation). The route enforces\nthis at the Zod boundary; OpenAPI's `required` cannot express\nOR-required cleanly.\n","properties":{"accountId":{"type":"string","minLength":1,"description":"WhatsApp SocialAccount ID."},"eventName":{"type":"string","enum":["LeadSubmitted","QualifiedLead","Purchase","AddToCart","InitiateCheckout","ViewContent","OrderCreated","OrderCanceled","OrderReturned"],"description":"Event names accepted by Meta's CAPI for Business\nMessaging. Other standard pixel events including `Lead`,\n`CompleteRegistration`, `Subscribe`, `Schedule`, `Contact`,\n`StartTrial`, `AddPaymentInfo`, `Search`, and\n`SubmitApplication` are rejected with subcode 2804066\n(\"Messaging Event Invalid Event Type\") on\n`action_source = business_messaging` events. Custom event\nnames are also rejected.\n\nUse `LeadSubmitted` (NOT `Lead`) when a lead comes in and\n`QualifiedLead` once your team qualifies it. `OrderCreated`,\n`OrderCanceled` and `OrderReturned` track an order placed in\nthe chat; send `value` and `currency` with them (and with\n`Purchase`) to report the order amount.\n"},"eventTime":{"type":"number","description":"Unix seconds. Defaults to the time of the request when\nomitted. Meta's attribution window is 7 days from click;\nevents older than that lose attribution.\n"},"eventId":{"type":"string","minLength":1,"description":"Stable dedup key. Reuse to suppress duplicate events\n(Meta dedupes against pixel events with the same id).\n"},"conversationId":{"type":"string","minLength":1,"description":"Zernio Conversation `_id` (preferred lookup). The\nconversation must have a captured `ctwa_clid` in metadata\n(set automatically by the WhatsApp webhook on the first\ninbound message after a CTWA ad click).\n"},"phoneE164":{"type":"string","minLength":1,"description":"Contact phone number, digits only with no '+'. When used\nin lieu of `conversationId`, the handler resolves to the\nmost recent CTWA-attributed conversation for this phone\non the supplied account.\n"},"value":{"type":"number","description":"Conversion value (e.g. order total)."},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code (e.g. `USD`)."},"contentIds":{"type":"array","items":{"type":"string"},"description":"Optional product / content identifiers."},"email":{"type":"string","format":"email","description":"User email. Normalized + SHA-256 hashed before sending to Meta."},"externalId":{"type":"string","description":"Stable customer identifier. Lowercased + SHA-256 hashed\nbefore sending to Meta.\n"},"testCode":{"type":"string","description":"Meta `test_event_code` passthrough, sent at the request root\n(a root-level `test_event_code` is accepted as an alias). The\nevent shows in Events Manager's Test Events tab for the\ndataset whose current test code matches. Meta still\nprocesses it like any other event, so remove it in production.\n"}}}}}},"responses":{"200":{"x-summary":"The event reached Meta but acceptance is not guaranteed: inspect `failures` for partial failures.","description":"Event submitted to Meta. Inspect `eventsFailed` and `failures[]`\nto detect partial failures. A 200 does not mean Meta accepted the\nevent; the status reflects \"request reached Meta\" only.\n","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["metaads"]},"eventsReceived":{"type":"integer","description":"Events accepted by Meta."},"eventsFailed":{"type":"integer","description":"Events rejected by Meta (see failures)."},"failures":{"type":"array","description":"Per-event failure detail. Empty when all events were\naccepted.\n","items":{"type":"object","properties":{"eventIndex":{"type":"integer","description":"Index into the submitted events array."},"eventId":{"type":"string","description":"Echoes back the eventId of the failed event."},"message":{"type":"string"},"code":{"oneOf":[{"type":"string"},{"type":"integer"}]},"platformError":{"type":"object","additionalProperties":true,"description":"Meta's own error for the rejected event, with credentials redacted:\n`message`, `type`, `code`, `error_subcode`, `error_user_title`,\n`error_user_msg` and `fbtrace_id` when Meta sends them. `message` above\nalready ends with `error_user_msg`. Absent when Meta returned no error body.\n"}}}},"traceId":{"type":"string","description":"Meta `fbtrace_id` for debugging. Surface in support\ntickets.\n"},"testCode":{"type":["string","null"],"description":"The test code sent to Meta, or `null` when the request carried none."}}}}}},"400":{"x-summary":"The body is invalid, for example `test_event_code` is empty or conflicts with the test code: fix it and resend.","description":"Invalid body, including a `test_event_code` that is not a non-empty string, or `testCode` and `test_event_code` with different values (`param: test_event_code`)."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Conversation not found."},"422":{"x-summary":"The account has no Meta dataset or the conversation has no click ID: set the dataset or use another conversation.","description":"Configuration missing (no `metaCapiDatasetId` on the account, set\nit via POST /v1/whatsapp/dataset) OR the resolved conversation has\nno captured `ctwa_clid`.\n"}}}},"/v1/ads/messaging":{"post":{"x-resource-group":"ads","operationId":"createMessagingAd","tags":["Messaging Ads"],"x-platforms":["meta"],"summary":"Create messaging ad","description":"Creates a Meta ad that opens a chat with you on WhatsApp, Messenger or Instagram Direct when someone taps it.\n\n### Destinations\n\n`destination` selects where the tapped ad opens a conversation:\n\n- WhatsApp\n- the Page's Messenger inbox\n- the linked Instagram account's Direct inbox\n\n`destinations` puts two or three of them on one ad set and lets Meta pick the app per viewer.\n\nThe ad set is created with the matching destination_type and CONVERSATIONS optimization. The campaign objective defaults to OUTCOME_ENGAGEMENT.\n\nThis endpoint supersedes POST /v1/ads/ctwa (deprecated, equivalent to `destination: whatsapp`).\n\n### Creatives and connections\n\nSupports single-creative and multi-creative shapes.\n\n- Existing posts and reels are supported through `platformPostId` (alias `existingPostId`) or `objectStoryId`, either per creative or at the top level. Omit fresh media and copy for that creative.\n- Optional `whatsappPhoneNumber` selects a number already paired with the Page (WhatsApp destination only).\n- `accountId` is a Facebook, Instagram or Meta ads (business login) connection.\n- `pageId` picks the Page when that connection was granted several.\n\n### Required fields per shape\n\nA missing one is a 400 naming it in `param`.\n\n- Always `accountId`, `adAccountId`, `name`, and exactly one of `destination` / `destinations`.\n- `budgetAmount` and `budgetType` unless `adSetId` or `existingCampaignId` is set, plus `endDate` for a lifetime budget.\n- Single image or video: `headline`, `body`, and exactly one of `imageUrl` / `video`. With `placementAssets`, `headline` and `body` only (the media comes from `placementAssets`).\n- `carouselCards`: `body` and the 2-10 cards; `headline` is optional, `imageUrl` / `video` / top-level `description` are a 400.\n- Existing post (`platformPostId` or `objectStoryId`): no copy or media fields.\n- `creatives[]`: the same rules per entry, with no top-level creative fields.\n- `welcomeMessage`, when sent: `text` plus exactly one of `prefillText` / `quickReplies`.\n\n### WhatsApp number prerequisite\n\nFor the WhatsApp destination, link the WhatsApp number to the Facebook Page used for the ad before creating it: Meta checks the pairing at creation. Link it from either:\n\n- the WhatsApp Business app (Settings > Business tools > Facebook & Instagram)\n- the Page settings (Linked accounts > WhatsApp)\n\nLinking does not affect the number's WhatsApp connection in Zernio (Cloud API or coexistence), so no reconnect or re-sync is needed.\n\nIf Meta creates a new ad set without the requested `whatsappPhoneNumber`, the 201 response carries a `warnings` entry. This can happen even when the number is linked (Meta can drop a Page's second linked number).\n\n### Idempotency\n\nThis endpoint is not idempotent at the platform level: a blind retry creates a second campaign/ad set/ad. Send an `Idempotency-Key` header to make retries safe.\n\nThe first request with a given key creates the ad and we store the response. A retry with the same key replays that exact response (with `Idempotent-Replayed: true`) instead of creating duplicates.\n\n- Reusing a key with a different body returns 422.\n- A key whose first request is still in flight returns 409 (retry after a short backoff).\n- If the first request is cut off mid-create (for example by a function timeout), its key can stay in progress and keep returning 409 until it expires. Use a new key to retry sooner, after checking whether the ad was created.\n\nKeys are scoped to your credential and expire after 24h.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CtwaAdRequestBody"},{"type":"object","properties":{"destination":{"type":"string","enum":["whatsapp","messenger","instagram_direct"],"description":"Where the conversation opens when the ad is tapped. Set this OR `destinations`, not both."},"destinations":{"type":"array","minItems":2,"maxItems":3,"uniqueItems":true,"items":{"type":"string","enum":["whatsapp","messenger","instagram_direct"]},"description":"Two or three messaging apps on ONE ad set, like Ads Manager's \"all messaging apps\". Set this OR `destination`, not both.\n\nThe ad set gets Meta's combined destination_type (e.g. MESSAGING_INSTAGRAM_DIRECT_MESSENGER_WHATSAPP) and the creative one CTA per app, so Meta opens the app each viewer is likeliest to answer from.\n\n- WhatsApp in the list still needs the Page paired with a WhatsApp Business number.\n- With `adSetId`, the existing ad set must already use that combined destination_type.\n"},"placementAssets":{"allOf":[{"$ref":"#/components/schemas/MetaPlacementAssets"}],"description":"A different image or video per placement on one messaging ad, e.g. a 4:5 image on Feed and a 9:16 image on Stories/Reels. Works on the single-creative shape and on attach (`adSetId`).\n\nReplaces top-level `imageUrl` / `video` (sending either alongside is a 400). `headline` and `body` stay required as the default copy. The CTA, `welcomeMessage` and `whatsappPhoneNumber` apply to every placement.\n\nSingle `destination` only. Meta cannot combine per-placement media with `destinations`: it drops the placement rules from a multi-destination creative, or refuses more than one call to action per placement rule with error 1885878. So that combination is a 400.\n\nAlso a 400 with `creatives[]`, `platformPostId`, `existingPostId` or `objectStoryId`, and on POST /v1/ads/call.\n"},"workflowId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"A workflow in the ad account's profile, stored on the ad. 404 when no such workflow exists in the profile.\n\nWhen someone clicks the ad, the workflow starts in the conversation the click opens (on the first message, a postback or a standalone referral carrying the ad id), ahead of keyword-matched workflows, if it is active on the receiving account.\n"},"validateOnly":{"type":"boolean","description":"Dry-runs the ad on Meta with execution_options validate_only, as ONE inline campaign + ad set + creative + ad (or creative + ad on the existing ad set with `adSetId`). Nothing is uploaded, created or stored; media is checked by URL.\n\n- **Supported:** one creative with `imageUrl`, image `placementAssets`, `carouselCards`, an existing `video.id`, or an existing post.\n- **Returns 400:** several creatives, a new `video.url` and video `placementAssets` (they need uploads first).\n\nSuccess returns 200 with per-node results; a Meta rejection returns the Meta error.\n"}}}]},"examples":{"existingPost":{"summary":"WhatsApp ad from an existing post","value":{"accountId":"69ca62446cb7b8cf4cb13603","adAccountId":"act_757082720485182","name":"WhatsApp existing post","destination":"whatsapp","creatives":[{"objectStoryId":"811889972008357_123456789"}],"budgetAmount":2.61,"budgetType":"daily","status":"PAUSED"}},"carousel":{"summary":"WhatsApp carousel ad (2-10 cards, each opening the chat)","value":{"accountId":"69ca62446cb7b8cf4cb13603","adAccountId":"act_757082720485182","name":"Rooms carousel","destination":"whatsapp","body":"Pick a room and message us to book.","carouselCards":[{"imageUrl":"https://example.com/room-a.jpg","headline":"Sea view room","description":"From 89 EUR per night"},{"imageUrl":"https://example.com/room-b.jpg","headline":"Garden suite"}],"welcomeMessage":{"text":"Hi! Which room are you interested in?","prefillText":"I want to book a room"},"budgetAmount":10,"budgetType":"daily","status":"PAUSED"}},"placementAssets":{"summary":"Instagram Direct ad with a 9:16 image on Stories and Reels","value":{"accountId":"69ca62446cb7b8cf4cb13603","adAccountId":"act_757082720485182","name":"Chat with us","destination":"instagram_direct","headline":"Chat with us","body":"Tap to send us a message.","placementAssets":{"defaultImageUrl":"https://example.com/feed-4x5.jpg","rules":[{"imageUrl":"https://example.com/story-9x16.jpg","placements":{"publisherPlatforms":["facebook","instagram"],"facebookPositions":["story","facebook_reels"],"instagramPositions":["story","reels"]}}]},"budgetAmount":10,"budgetType":"daily","status":"PAUSED"}}}}}},"responses":{"200":{"x-summary":"Meta accepted every node of the validation-only request and nothing was created.","description":"`validateOnly: true` only. Meta accepted every node; nothing was created.","content":{"application/json":{"schema":{"type":"object","required":["validateOnly","results","message"],"properties":{"validateOnly":{"type":"boolean","description":"Always true."},"results":{"type":"array","items":{"type":"object","required":["node","status"],"properties":{"node":{"type":"string","enum":["campaign","adSet","creative","ad"]},"status":{"type":"string","enum":["validated","skipped","unverified"]},"reason":{"type":"string","description":"On unverified: why Meta could not dry-run this node although the other nodes passed."}}}},"message":{"type":"string"}}}}}},"201":{"x-summary":"The ads were created and submitted for review: read the response by its `adType` value.","description":"Ad(s) created and submitted for review. The route shares its handler with\n`POST /v1/ads/ctwa`, so the body is the same tagged union discriminated by\n`adType`: `single` carries `{ adType, ad, message }`, and `multi` carries\n`{ adType, ads, platformCampaignId, platformAdSetId, message }`.\n","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CtwaSingleResponse"},{"$ref":"#/components/schemas/CtwaMultiResponse"}],"discriminator":{"propertyName":"adType","mapping":{"single":"#/components/schemas/CtwaSingleResponse","multi":"#/components/schemas/CtwaMultiResponse"}}}}}},"400":{"description":"Invalid input"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The free live ads limit is reached without a card, or the account is not selected: add a card or select it.","description":"Returned with these codes:\n\n- `ads_allowance_exceeded`: the team has no payment method on file and has reached the 500 free live ads. Add a card to resume.\n- `ad_account_not_selected`: the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n- `ad_account_not_selected` fix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection), or use a connection that has it selected.\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"description":"No Facebook Page resolved for the account"},"429":{"$ref":"#/components/responses/MetaAdAccountWriteLimited"},"502":{"x-summary":"Meta accepted the request but failed to produce the image, for example from an upload or processing timeout.","description":"Meta accepted the request then failed to produce the media (upload session, chunk transfer, processing timeout, or a response with no image hash). Inspect `platformError.reason`."}}}},"/v1/ads/call":{"post":{"x-resource-group":"ads","operationId":"createCallAd","tags":["Messaging Ads"],"x-platforms":["meta"],"summary":"Create Click-to-Call ad","description":"Creates a Meta ad with a Call Now button that dials your phone number, optimized for quality calls.\n\nSame shape and flow as POST /v1/ads/ctwa, but the CTA is CALL_NOW dialing `phoneNumber` via a tel: link. Supports the same single-creative and multi-creative shapes as CTWA.\n\n- The ad set is destination_type PHONE_CALL optimizing QUALITY_CALL.\n- The campaign objective defaults to OUTCOME_LEADS.\n\n### Idempotency\n\nThis endpoint is not idempotent at the platform level: a blind retry creates a second campaign/ad set/ad. Send an `Idempotency-Key` header to make retries safe.\n\nThe first request with a given key creates the ad and we store the response. A retry with the same key replays that exact response (with `Idempotent-Replayed: true`) instead of creating duplicates.\n\n- Reusing a key with a different body returns 422.\n- A key whose first request is still in flight returns 409 (retry after a short backoff).\n- If the first request is cut off mid-create (for example by a function timeout), its key can stay in progress and keep returning 409 until it expires. Use a new key to retry sooner, after checking whether the ad was created.\n\nKeys are scoped to your credential and expire after 24h.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CtwaAdRequestBody"},{"type":"object","required":["phoneNumber","linkUrl"],"properties":{"phoneNumber":{"type":"string","description":"E.164 number the CALL_NOW CTA dials (e.g. +34600111222)."},"linkUrl":{"type":"string","format":"uri","description":"Website shown as the creative's link. Required: Meta rejects tel: as link_data.link; the phone number rides only the CTA."}}}]}}}},"responses":{"201":{"x-summary":"The ads were created and submitted for review: read the response by its `adType` value.","description":"Ad(s) created and submitted for review. The route shares its handler with\n`POST /v1/ads/ctwa`, so the body is the same tagged union discriminated by\n`adType`: `single` carries `{ adType, ad, message }`, and `multi` carries\n`{ adType, ads, platformCampaignId, platformAdSetId, message }`.\n","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CtwaSingleResponse"},{"$ref":"#/components/schemas/CtwaMultiResponse"}],"discriminator":{"propertyName":"adType","mapping":{"single":"#/components/schemas/CtwaSingleResponse","multi":"#/components/schemas/CtwaMultiResponse"}}}}}},"400":{"description":"Invalid input"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Access is denied: the free ads allowance is used up, the ad account is not selected, or the Facebook user lacks permissions.","description":"Returned with one of these codes:\n\n- `ads_allowance_exceeded`: the team has no payment method on file and has reached the 500 free live ads. Add a card to resume.\n- `ad_account_not_selected`: the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n- `ad_account_not_selected`, fix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.\n- `insufficient_permissions`: the Facebook user behind the connection's token lacks the Advertise permission on the Meta ad account, or the token lacks `ads_management` (Meta subcode 2490585, 2490591 or 4841020; see `ErrorResponse.details`).\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"description":"No Facebook Page resolved for the account"},"429":{"$ref":"#/components/responses/MetaAdAccountWriteLimited"},"502":{"x-summary":"Meta accepted the request but failed to produce the image, for example from an upload or processing timeout.","description":"Meta accepted the request then failed to produce the media (upload session, chunk transfer, processing timeout, or a response with no image hash). Inspect `platformError.reason`."}}}},"/v1/ads/ctwa":{"post":{"x-resource-group":"ads","operationId":"createCtwaAd","tags":["Messaging Ads"],"x-platforms":["meta"],"summary":"Create CTWA ad (deprecated)","deprecated":true,"description":"Deprecated: use POST /v1/ads/messaging with `destination: whatsapp`. This endpoint stays available for back-compat; no removal planned.\n\nCreates one or more Click-to-WhatsApp (CTWA) ads on Meta under a single campaign and ad set. When tapped, each ad opens a WhatsApp conversation with the business attached to the supplied Facebook Page.\n\nThe full hierarchy (campaign, ad set, creative(s), ad(s)) is created and activated in one call. The CTA is locked to WHATSAPP_MESSAGE and the destination is hard-coded to api.whatsapp.com/send. Meta resolves the actual WhatsApp number from the Page-to-WA pairing configured in Page settings or Business Manager.\n\n### Request shapes\n\nTwo mutually exclusive shapes:\n\n- **Single-creative**: supply top-level `headline`, `body`, and one of `imageUrl` / `video`, or a `platformPostId` / `objectStoryId` reference. Creates 1 campaign + 1 ad set + 1 ad.\n- **Multi-creative**: supply a `creatives[]` array with N entries (each carrying fresh media and copy or an existing post reference). Creates 1 campaign + 1 ad set + N ads sharing budget and targeting.\n\nMulti-creative lets Meta A/B the creatives inside a single auction instead of fragmenting budget across N parallel campaigns. It is recommended when launching multiple creative variants for the same campaign.\n\nExisting posts and reels are supported through `platformPostId` (alias `existingPostId`) or `objectStoryId`, either per creative or at the top level. Omit fresh media and copy for that creative.\n\nOptional `whatsappPhoneNumber` selects a number already paired with the Page (WhatsApp destination only).\n\n### Attach shape\n\nSend `adSetId` (with either creative shape) to add the ads to an EXISTING messaging ad set instead of building a campaign. The ad set keeps its learning phase, which makes this the way to refresh a CTWA creative without resetting delivery.\n\nThe ad set then owns budget, targeting and schedule. So `budgetAmount`, `budgetType`, `endDate`, `objective`, `countries`, `interests` and `audienceId` are rejected with a 400 alongside it rather than silently dropped.\n\nThe target ad set's `destination_type` must match the ad's destination (a WhatsApp ad needs a `WHATSAPP` ad set). Otherwise Meta would accept an ad that never delivers.\n\n### Prerequisites\n\nEnforced by Meta and surfaced as platform_error on failure:\n\n- The Facebook Page must be paired with a verified WhatsApp Business number.\n- The WhatsApp Business Account must be business-verified.\n- The Meta access token must carry ads_management.\n\n### WhatsApp number prerequisite\n\nLink the WhatsApp number to the Facebook Page used for the ad before creating it: Meta checks the pairing at creation. Link it from either:\n\n- the WhatsApp Business app (Settings > Business tools > Facebook & Instagram);\n- the Page settings (Linked accounts > WhatsApp).\n\nLinking does not affect the number's WhatsApp connection in Zernio (Cloud API or coexistence), so no reconnect or re-sync is needed.\n\nIf Meta creates a new ad set without the requested `whatsappPhoneNumber`, the 201 response carries a `warnings` entry. This can happen even when the number is linked (Meta can drop a Page's second linked number).\n\n### Idempotency\n\nThis endpoint is not idempotent at the platform level: a blind retry creates a second campaign/ad set/ad. Send an `Idempotency-Key` header to make retries safe.\n\n- The first request with a given key creates the ad and we store the response.\n- A retry with the same key replays that exact response (with `Idempotent-Replayed: true`) instead of creating duplicates.\n- Reusing a key with a different body returns 422.\n- A key whose first request is still in flight returns 409 (retry after a short backoff).\n- If the first request is cut off mid-create (for example by a function timeout), its key can stay in progress and keep returning 409 until it expires. Use a new key to retry sooner, after checking whether the ad was created.\n- Keys are scoped to your credential and expire after 24h.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CtwaAdRequestBody"},"example":{"accountId":"69ca62446cb7b8cf4cb13603","adAccountId":"act_757082720485182","name":"WhatsApp existing post","creatives":[{"objectStoryId":"811889972008357_123456789"}],"budgetAmount":2.61,"budgetType":"daily","status":"PAUSED"}}}},"responses":{"201":{"x-summary":"The CTWA ads were created and submitted to Meta for review: read the response by its `adType` value.","description":"CTWA ad(s) created and submitted to Meta for review. Response is a\ntagged union discriminated by `adType`:\n\n- `adType: \"single\"` → single-creative request: `{ adType, ad,\n  message }` where `ad` is the persisted Ad document.\n- `adType: \"multi\"` → multi-creative request: `{ adType, ads,\n  platformCampaignId, platformAdSetId, message }` where `ads` is\n  the array of N persisted Ad documents all sharing the returned\n  campaign and ad set IDs.\n\nGenerated SDK clients can narrow on `adType` instead of sniffing\nfor field presence.\n","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CtwaSingleResponse"},{"$ref":"#/components/schemas/CtwaMultiResponse"}],"discriminator":{"propertyName":"adType","mapping":{"single":"#/components/schemas/CtwaSingleResponse","multi":"#/components/schemas/CtwaMultiResponse"}}}}}},"400":{"description":"Invalid body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Access is denied: the free ads allowance is used up, the ad account is not selected, or the Facebook user lacks permissions.","description":"Forbidden. Also returned with these codes:\n\n- `ads_allowance_exceeded`: the team has no payment method on file and has reached the 500 free live ads. Add a card to resume.\n- `ad_account_not_selected`: the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n- `ad_account_not_selected` fix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection), or use a connection that has it selected.\n- `insufficient_permissions`: the Facebook user behind the token lacks the Advertise permission on the Meta ad account, or the token lacks `ads_management` (Meta subcode 2490585, 2490591 or 4841020; see `ErrorResponse.details`).\n"},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"x-summary":"The page has no verified WhatsApp number or the ad account is unusable: connect a verified number or fix the account status.","description":"Page is not connected to a verified WhatsApp number, or code `ad_account_unusable` when Meta refuses writes on the ad account (see `ErrorResponse.details`)."},"429":{"$ref":"#/components/responses/MetaAdAccountWriteLimited"},"502":{"x-summary":"Meta rejected the request, for example because the WhatsApp Business Account lacks business verification.","description":"Meta rejected the request (e.g. WABA business verification\nmissing). Inspect `platformError` for the upstream Meta payload.\n"}}}},"/v1/accounts/{accountId}/custom-conversions":{"get":{"x-resource-group":"accounts","operationId":"listCustomConversions","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"List custom conversions","description":"Lists a Meta ad account's custom conversions, including archived ones.\n\nThe ad account's Meta custom conversions, including archived ones (`isArchived`).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Meta ads SocialAccount id."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"Meta ad account id (act_<n>)."}],"responses":{"200":{"description":"Custom conversions","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomConversion"}}}}}}},"400":{"description":"Invalid input, or Meta rejected the query"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access, a permission or the account selection is missing: enable access, grant it, or add the ad account to the selection.","description":"Ads access required, or the token lacks the ads permissions.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection), or use a connection that has it selected."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}},"post":{"x-resource-group":"accounts","operationId":"createCustomConversion","tags":["Ad Accounts"],"x-platforms":["meta"],"summary":"Create custom conversion","description":"Creates a Meta custom conversion for ads to optimise toward, reusing an existing one with the same name and pixel.\n\nIt provisions the Meta custom conversion an ads flow optimises toward, and hands back the `customConversionId` for `promotedObject.customConversionId` on POST /v1/ads/create. This removes the manual \"create it in Ads Manager first\" step.\n\n### Reuse is ours, not Meta's\n\nMeta's create is not idempotent, so a retried request would otherwise mint a duplicate carrying none of the original's optimisation history.\n\nA non-archived conversion with the same `name` on the same `pixelId` is returned instead of created, with `reused: true` and a 200 rather than a 201.\n\n### Rule\n\n`rule` is forwarded verbatim in Meta's own grammar (e.g. `{\"url\": {\"i_contains\": \"thank-you\"}}`). Meta validates it and rejects a malformed one with \"A conversion rule is required at creation time\".\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Meta ads SocialAccount id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["adAccountId","name","pixelId","customEventType","rule"],"properties":{"adAccountId":{"type":"string","description":"Platform ad account id (Meta act_<n>, Google customer id, LinkedIn account id, ...)."},"name":{"type":"string","maxLength":255,"description":"Also the reuse key, together with pixelId."},"pixelId":{"type":"string","description":"Meta pixel id (event_source_id). From GET /v1/accounts/{accountId}/tracking-tags."},"customEventType":{"type":"string","description":"Meta custom_event_type, e.g. LEAD, PURCHASE, OTHER."},"rule":{"type":"object","description":"Meta conversion rule, forwarded verbatim."}}}}}},"responses":{"200":{"description":"An existing custom conversion was reused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomConversionResult"}}}},"201":{"description":"Custom conversion created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomConversionResult"}}}},"400":{"description":"Invalid input, or Meta rejected the conversion (bad rule, per-account cap reached)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access, a permission or the account selection is missing: enable access, grant it, or add the ad account to the selection.","description":"Ads access required, or the token lacks the ads permissions.\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix it, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"}}}},"/v1/accounts/{accountId}/business-agent":{"get":{"x-resource-group":"messages","operationId":"getBusinessAgentStatus","tags":["Business Agent"],"summary":"Get agent setup status","description":"One read that says where the merchant is with the Meta Business Agent. It reports:\n\n- whether the number is eligible\n- whether the Meta Business Agent terms are accepted\n- whether an agent exists\n- whether it is on\n- its settings\n\n### Pending steps\n\n- `manualSteps` lists what Zernio can verify is still pending (accepting the terms in WhatsApp Manager).\n- `unverifiedSteps` lists what Meta exposes no state for (the payment method in Billing Hub).\n\nNever fails for those pre-setup states; it reports them as flags.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"responses":{"200":{"description":"Setup status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentStatus"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/onboard":{"post":{"x-resource-group":"messages","operationId":"onboardBusinessAgent","tags":["Business Agent"],"summary":"Create the agent","description":"Creates the Meta Business Agent on the number and schedules Meta's data preparation.\n\nRequires the terms to be accepted. Eligibility is checked first, and an ineligible number answers 403 `business_agent_not_eligible`.\n\n### Setup order\n\nNot idempotent: call it once, then:\n\n1. Configure knowledge and skills.\n2. Enable it through the settings.\n\nConfiguration calls made in the first minute can still answer `business_agent_not_found` while Meta prepares the workspace.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"responses":{"201":{"description":"Agent created","content":{"application/json":{"schema":{"type":"object","required":["agentId"],"properties":{"agentId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"},"409":{"description":"Meta rejected the state change (code business_agent_conflict)."}}}},"/v1/accounts/{accountId}/business-agent/settings":{"get":{"x-resource-group":"messages","operationId":"listBusinessAgentSettings","tags":["Business Agent"],"summary":"List agent settings","description":"Settings of every agent configured on the number (normally one). Pass `agentId` to read one.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"name":"agentId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"type":"object","required":["settings"],"properties":{"settings":{"type":"array","items":{"$ref":"#/components/schemas/BusinessAgentSettings"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"patch":{"x-resource-group":"messages","operationId":"updateBusinessAgentSettings","tags":["Business Agent"],"summary":"Update agent settings","description":"Partial update: fields you omit keep their value.\n\n- `rollout.enabled: true` turns the agent on for new conversations; `false` stops it on every thread.\n- Turning it on for `EVERYONE` needs a payment method on the Business Agent billable account (Meta accepts the call but delivers nothing without one).\n- `ALLOWLISTED_ONLY` does not need one, which is how you test with a few numbers before billing.\n- `never_say_phrases` replaces the whole list.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"name":"agentId","in":"query","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rollout":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"}}},"handoff":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"},"message":{"type":"string","maxLength":1024},"message_selection":{"type":"string","enum":["DEFAULT","AGENT","CUSTOM"]}}},"followup":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"},"followup_interval_in_seconds":{"type":"integer","enum":[0,300,900,1800,3600,7200,28800,86400]},"message":{"type":"string","maxLength":1024}}},"ai_audience":{"type":"string","enum":["EVERYONE","ALLOWLISTED_ONLY"]},"never_say_phrases":{"type":"array","items":{"type":"string"},"description":"Exact phrases the agent must never say; the full replacement list."}}}}}},"responses":{"200":{"description":"Updated settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentSettings"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/allowlist":{"get":{"x-resource-group":"messages","operationId":"listBusinessAgentAllowlist","tags":["Business Agent"],"summary":"List allowlisted consumers","description":"Consumers the agent answers while `ai_audience` is ALLOWLISTED_ONLY.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"responses":{"200":{"description":"Allowlist","content":{"application/json":{"schema":{"type":"object","required":["entries"],"properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/BusinessAgentAllowlistEntry"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"post":{"x-resource-group":"messages","operationId":"addBusinessAgentAllowlistEntry","tags":["Business Agent"],"summary":"Allowlist a consumer","description":"One E.164 number per call. Not idempotent.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["consumer_phone_number"],"properties":{"consumer_phone_number":{"type":"string","example":"+34600000000"}}}}}},"responses":{"201":{"description":"Entry added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentAllowlistEntry"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/allowlist/{entryId}":{"delete":{"x-resource-group":"messages","operationId":"removeBusinessAgentAllowlistEntry","tags":["Business Agent"],"summary":"Remove an allowlisted consumer","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"name":"entryId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/BusinessAgentDeleted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/business-information":{"get":{"x-resource-group":"messages","operationId":"getBusinessAgentBusinessInformation","tags":["Business Agent"],"summary":"Get business information","description":"Payment methods, return policy, how to buy, shipping, description and contact details the agent answers from. Empty values until configured.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"responses":{"200":{"description":"Business information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentBusinessInformation"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"put":{"x-resource-group":"messages","operationId":"replaceBusinessAgentBusinessInformation","tags":["Business Agent"],"summary":"Replace business information","description":"Full replacement: every field you send overwrites the stored value; fields you omit are cleared.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentBusinessInformation"}}}},"responses":{"200":{"description":"Stored business information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentBusinessInformation"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"delete":{"x-resource-group":"messages","operationId":"resetBusinessAgentBusinessInformation","tags":["Business Agent"],"summary":"Reset business information","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"responses":{"200":{"$ref":"#/components/responses/BusinessAgentDeleted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/faqs":{"get":{"x-resource-group":"messages","operationId":"listBusinessAgentFaqs","tags":["Business Agent"],"summary":"List FAQs","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"responses":{"200":{"description":"FAQs","content":{"application/json":{"schema":{"type":"object","required":["faqs"],"properties":{"faqs":{"type":"array","items":{"$ref":"#/components/schemas/BusinessAgentFaq"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"post":{"x-resource-group":"messages","operationId":"createBusinessAgentFaq","tags":["Business Agent"],"summary":"Create a FAQ","description":"One specific question per entry; beyond a few hundred entries retrieval quality drops. Not idempotent.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentFaqInput"}}}},"responses":{"201":{"description":"FAQ created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentFaq"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"},"409":{"description":"Meta rejected the entry (code business_agent_conflict)."}}}},"/v1/accounts/{accountId}/business-agent/faqs/{faqId}":{"get":{"x-resource-group":"messages","operationId":"getBusinessAgentFaq","tags":["Business Agent"],"summary":"Get a FAQ","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"name":"faqId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"FAQ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentFaq"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"put":{"x-resource-group":"messages","operationId":"updateBusinessAgentFaq","tags":["Business Agent"],"summary":"Update a FAQ","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"name":"faqId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentFaqInput"}}}},"responses":{"200":{"description":"FAQ updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentFaq"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"delete":{"x-resource-group":"messages","operationId":"deleteBusinessAgentFaq","tags":["Business Agent"],"summary":"Delete a FAQ","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"name":"faqId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/BusinessAgentDeleted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/websites":{"get":{"x-resource-group":"messages","operationId":"listBusinessAgentWebsites","tags":["Business Agent"],"summary":"List crawled websites","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"responses":{"200":{"description":"Websites","content":{"application/json":{"schema":{"type":"object","required":["websites"],"properties":{"websites":{"type":"array","items":{"$ref":"#/components/schemas/BusinessAgentWebsite"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"post":{"x-resource-group":"messages","operationId":"addBusinessAgentWebsite","tags":["Business Agent"],"summary":"Add a website to crawl","description":"Meta crawls the site into the agent knowledge and recrawls it periodically; check `crawl_status` and `crawl_error` on read. Not idempotent.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentWebsiteInput"}}}},"responses":{"201":{"description":"Website added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentWebsite"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/websites/{websiteId}":{"get":{"x-resource-group":"messages","operationId":"getBusinessAgentWebsite","tags":["Business Agent"],"summary":"Get a crawled website","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"name":"websiteId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Website","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentWebsite"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"put":{"x-resource-group":"messages","operationId":"updateBusinessAgentWebsite","tags":["Business Agent"],"summary":"Update a crawled website","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"name":"websiteId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentWebsiteInput"}}}},"responses":{"200":{"description":"Website updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentWebsite"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"delete":{"x-resource-group":"messages","operationId":"deleteBusinessAgentWebsite","tags":["Business Agent"],"summary":"Remove a crawled website","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"name":"websiteId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/BusinessAgentDeleted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/files":{"get":{"x-resource-group":"messages","operationId":"listBusinessAgentFiles","tags":["Business Agent"],"summary":"List knowledge files","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"responses":{"200":{"description":"Files","content":{"application/json":{"schema":{"type":"object","required":["files"],"properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/BusinessAgentKnowledgeFile"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"post":{"x-resource-group":"messages","operationId":"uploadBusinessAgentFile","tags":["Business Agent"],"summary":"Upload a knowledge file","description":"Uploads a knowledge file. Not idempotent.\n\nAccepted types: pdf, doc, docx, png, jpg, jpeg, plus csv and xlsx when Meta enabled extraction on the asset. Meta's limit is 100 MB.\n\n### Two ways to send the file\n\n- JSON `{ url, fileName }`: Zernio downloads the file (public https URL, no redirects, capped at 100 MB) and forwards it. Use this for anything above a few megabytes.\n- multipart form-data with a `file` part (and an optional `fileName`): bounded by the request body limit of about 4.5 MB. Larger uploads must use the `url` form.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Publicly downloadable file URL."},"fileName":{"type":"string","description":"Defaults to the last path segment of the URL."}}}},"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"fileName":{"type":"string"}}}}}},"responses":{"201":{"description":"File uploaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentKnowledgeFile"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"},"413":{"x-summary":"The file is larger than 100 MB: upload a smaller file.","description":"File larger than 100 MB (code payload_too_large). A multipart body above the request limit is rejected by the host before the route runs."}}}},"/v1/accounts/{accountId}/business-agent/files/{fileId}":{"get":{"x-resource-group":"messages","operationId":"getBusinessAgentFile","tags":["Business Agent"],"summary":"Get a knowledge file","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"name":"fileId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"File","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentKnowledgeFile"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"delete":{"x-resource-group":"messages","operationId":"deleteBusinessAgentFile","tags":["Business Agent"],"summary":"Delete a knowledge file","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"name":"fileId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/BusinessAgentDeleted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/skills":{"get":{"x-resource-group":"messages","operationId":"listBusinessAgentSkills","tags":["Business Agent"],"summary":"List skills","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"responses":{"200":{"description":"Skills","content":{"application/json":{"schema":{"type":"object","required":["skills"],"properties":{"skills":{"type":"array","items":{"$ref":"#/components/schemas/BusinessAgentSkill"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"post":{"x-resource-group":"messages","operationId":"createBusinessAgentSkill","tags":["Business Agent"],"summary":"Create a skill","description":"Behavioral instructions in the brand voice. Reads back `pending_review` until Meta content review passes it. Not idempotent.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentSkillInput"}}}},"responses":{"201":{"description":"Skill created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentSkill"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/skills/{skillId}":{"get":{"x-resource-group":"messages","operationId":"getBusinessAgentSkill","tags":["Business Agent"],"summary":"Get a skill","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"name":"skillId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Skill","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentSkill"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"put":{"x-resource-group":"messages","operationId":"updateBusinessAgentSkill","tags":["Business Agent"],"summary":"Update a skill","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"name":"skillId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentSkillInput"}}}},"responses":{"200":{"description":"Skill updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentSkill"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"delete":{"x-resource-group":"messages","operationId":"deleteBusinessAgentSkill","tags":["Business Agent"],"summary":"Delete a skill","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"name":"skillId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/BusinessAgentDeleted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/ui-skills":{"get":{"x-resource-group":"messages","operationId":"listBusinessAgentUiSkills","tags":["Business Agent"],"summary":"List UI skills","description":"Cursor paged; follow `paging.cursors.after` until `paging.next` is absent.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"name":"before","in":"query","required":false,"schema":{"type":"string"}},{"name":"after","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"UI skills","content":{"application/json":{"schema":{"type":"object","required":["uiSkills"],"properties":{"uiSkills":{"type":"array","items":{"$ref":"#/components/schemas/BusinessAgentUiSkill"}},"paging":{"type":"object","additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"post":{"x-resource-group":"messages","operationId":"createBusinessAgentUiSkill","tags":["Business Agent"],"summary":"Create a UI skill","description":"Tells the agent when to send a rich component (CTA URL button, image, carousel, list, reply buttons, location, Flow) and what to put in it. Not idempotent.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentUiSkillInput"}}}},"responses":{"201":{"description":"UI skill created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentUiSkill"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/ui-skills/{uiSkillId}":{"get":{"x-resource-group":"messages","operationId":"getBusinessAgentUiSkill","tags":["Business Agent"],"summary":"Get a UI skill","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"name":"uiSkillId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"UI skill","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentUiSkill"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"put":{"x-resource-group":"messages","operationId":"updateBusinessAgentUiSkill","tags":["Business Agent"],"summary":"Update a UI skill","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"name":"uiSkillId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentUiSkillInput"}}}},"responses":{"200":{"description":"UI skill updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentUiSkill"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"delete":{"x-resource-group":"messages","operationId":"deleteBusinessAgentUiSkill","tags":["Business Agent"],"summary":"Delete a UI skill","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"name":"uiSkillId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/BusinessAgentDeleted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/connectors":{"get":{"x-resource-group":"messages","operationId":"listBusinessAgentConnectors","tags":["Business Agent"],"summary":"List connectors","description":"External APIs the agent may call. `connection_status` says whether Meta can currently reach each one.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"responses":{"200":{"description":"Connectors","content":{"application/json":{"schema":{"type":"object","required":["connectors"],"properties":{"connectors":{"type":"array","items":{"$ref":"#/components/schemas/BusinessAgentConnector"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"post":{"x-resource-group":"messages","operationId":"createBusinessAgentConnector","tags":["Business Agent"],"summary":"Create a connector","description":"Base URL plus how to authenticate (OAuth client credentials, API key or none). Names are unique per number. Not idempotent.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentConnectorInput"}}}},"responses":{"201":{"description":"Connector created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentConnector"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"},"409":{"description":"A connector with that name already exists (code business_agent_conflict)."}}}},"/v1/accounts/{accountId}/business-agent/connectors/{connectorId}":{"get":{"x-resource-group":"messages","operationId":"getBusinessAgentConnector","tags":["Business Agent"],"summary":"Get a connector","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"$ref":"#/components/parameters/BusinessAgentConnectorId"}],"responses":{"200":{"description":"Connector","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentConnector"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"put":{"x-resource-group":"messages","operationId":"updateBusinessAgentConnector","tags":["Business Agent"],"summary":"Update a connector","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"$ref":"#/components/parameters/BusinessAgentConnectorId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentConnectorInput"}}}},"responses":{"200":{"description":"Connector updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentConnector"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"delete":{"x-resource-group":"messages","operationId":"deleteBusinessAgentConnector","tags":["Business Agent"],"summary":"Delete a connector","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"$ref":"#/components/parameters/BusinessAgentConnectorId"}],"responses":{"200":{"$ref":"#/components/responses/BusinessAgentDeleted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/connectors/{connectorId}/credentials":{"post":{"x-resource-group":"messages","operationId":"setBusinessAgentConnectorCredentials","tags":["Business Agent"],"summary":"Set connector credentials","description":"Set or rotate the connector's credentials in place: `kind: api_key`, `kind: oauth`\n(client credentials) or `kind: certificate` (mTLS client certificate). Meta has no call\nthat removes a credential layer; change the connector's `auth_type` or delete it instead.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"$ref":"#/components/parameters/BusinessAgentConnectorId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["kind","api_key_config"],"properties":{"kind":{"type":"string","enum":["api_key"]},"api_key_config":{"$ref":"#/components/schemas/BusinessAgentApiKeyConfig"}}},{"type":"object","required":["kind","oauth_config"],"properties":{"kind":{"type":"string","enum":["oauth"]},"oauth_config":{"$ref":"#/components/schemas/BusinessAgentOAuthClientCredentials"}}},{"type":"object","required":["kind","client_certificate","client_key"],"properties":{"kind":{"type":"string","enum":["certificate"]},"client_certificate":{"type":"string","description":"PEM."},"client_key":{"type":"string","description":"PEM."},"ca_certificate":{"type":"string","description":"PEM."}}}]}}}},"responses":{"200":{"description":"Connector with the new credential metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentConnector"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/connectors/{connectorId}/refresh-tools":{"post":{"x-resource-group":"messages","operationId":"refreshBusinessAgentConnectorTools","tags":["Business Agent"],"summary":"Refresh MCP connector tools","description":"Re-discovers the tools of an MCP connector. A failed discovery keeps the previous tool set and reports an ERROR sync status inside a 200.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"$ref":"#/components/parameters/BusinessAgentConnectorId"}],"responses":{"200":{"description":"Connector with updated tool sync metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentConnector"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/connectors/{connectorId}/logs":{"get":{"x-resource-group":"messages","operationId":"getBusinessAgentConnectorLogs","tags":["Business Agent"],"summary":"Get connector failure logs","description":"Third-party failures over the last 7 days (window at most 7 days, default the last 24 hours). Each entry carries `failure_code_name` and `error_message`.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"$ref":"#/components/parameters/BusinessAgentConnectorId"},{"name":"startTime","in":"query","required":false,"schema":{"type":"integer"},"description":"Unix seconds."},{"name":"endTime","in":"query","required":false,"schema":{"type":"integer"},"description":"Unix seconds."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000}},{"name":"toolId","in":"query","required":false,"schema":{"type":"string"}},{"name":"includeStats","in":"query","required":false,"schema":{"type":"boolean"},"description":"Add success rate and latency percentiles."},{"name":"summaryOnly","in":"query","required":false,"schema":{"type":"boolean"},"description":"Aggregate failure patterns instead of entries."},{"name":"topN","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"Logs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"stats":{"type":"object","additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/connectors/{connectorId}/tools":{"get":{"x-resource-group":"messages","operationId":"listBusinessAgentConnectorTools","tags":["Business Agent"],"summary":"List connector tools","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"$ref":"#/components/parameters/BusinessAgentConnectorId"}],"responses":{"200":{"description":"Tools","content":{"application/json":{"schema":{"type":"object","required":["tools"],"properties":{"tools":{"type":"array","items":{"$ref":"#/components/schemas/BusinessAgentConnectorTool"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"post":{"x-resource-group":"messages","operationId":"createBusinessAgentConnectorTool","tags":["Business Agent"],"summary":"Create a connector tool","description":"One operation on the connector, with the request definition Meta uses to build the outbound call from the conversation. Type the body params explicitly. Not idempotent.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"$ref":"#/components/parameters/BusinessAgentConnectorId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentConnectorToolInput"}}}},"responses":{"201":{"description":"Tool created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentConnectorTool"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/connectors/{connectorId}/tools/{toolId}":{"get":{"x-resource-group":"messages","operationId":"getBusinessAgentConnectorTool","tags":["Business Agent"],"summary":"Get a connector tool","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"$ref":"#/components/parameters/BusinessAgentConnectorId"},{"$ref":"#/components/parameters/BusinessAgentToolId"}],"responses":{"200":{"description":"Tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentConnectorTool"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"put":{"x-resource-group":"messages","operationId":"updateBusinessAgentConnectorTool","tags":["Business Agent"],"summary":"Update a connector tool","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"$ref":"#/components/parameters/BusinessAgentConnectorId"},{"$ref":"#/components/parameters/BusinessAgentToolId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentConnectorToolInput"}}}},"responses":{"200":{"description":"Tool updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentConnectorTool"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"delete":{"x-resource-group":"messages","operationId":"deleteBusinessAgentConnectorTool","tags":["Business Agent"],"summary":"Delete a connector tool","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"$ref":"#/components/parameters/BusinessAgentConnectorId"},{"$ref":"#/components/parameters/BusinessAgentToolId"}],"responses":{"200":{"$ref":"#/components/responses/BusinessAgentDeleted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/connectors/{connectorId}/tools/{toolId}/run":{"post":{"x-resource-group":"messages","operationId":"runBusinessAgentConnectorTool","tags":["Business Agent"],"summary":"Run a connector tool once","description":"Executes the tool against the merchant API and returns the raw upstream result, to check a connector before the agent relies on it.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"$ref":"#/components/parameters/BusinessAgentConnectorId"},{"$ref":"#/components/parameters/BusinessAgentToolId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["input"],"properties":{"input":{"type":"string","description":"JSON string with the tool arguments."}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"schema":{"type":"object","properties":{"output":{"type":"string"},"status":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/budget":{"get":{"x-resource-group":"messages","operationId":"getBusinessAgentBudget","tags":["Business Agent"],"summary":"Get usage budgets","description":"Caps over rolling windows for the Business Manager that owns the number. An empty list means unlimited.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"responses":{"200":{"description":"Budgets","content":{"application/json":{"schema":{"type":"object","required":["budgets"],"properties":{"budgets":{"type":"array","items":{"$ref":"#/components/schemas/BusinessAgentBudget"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"put":{"x-resource-group":"messages","operationId":"replaceBusinessAgentBudget","tags":["Business Agent"],"summary":"Replace usage budgets","description":"The full desired set: budgets left out are removed, an empty list returns to unlimited. Pass `budget_id` to edit one in place. When a cap is hit the agent finishes its turn, stops answering and hands the thread to a human until the window rolls over.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["budgets"],"properties":{"budgets":{"type":"array","items":{"$ref":"#/components/schemas/BusinessAgentBudget"}}}}}}},"responses":{"200":{"description":"Budgets after the update","content":{"application/json":{"schema":{"type":"object","required":["budgets"],"properties":{"budgets":{"type":"array","items":{"$ref":"#/components/schemas/BusinessAgentBudget"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/test-messages":{"post":{"x-resource-group":"messages","operationId":"sendBusinessAgentTestMessage","tags":["Business Agent"],"summary":"Send a test message","description":"Runs the message through the full agent pipeline in Meta sandbox with no WhatsApp user and no token billing. Pass back `conversationId` to continue a thread. Meta rate-limits it per number per hour.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","maxLength":4096},"conversationId":{"type":"string"}}}}}},"responses":{"200":{"description":"Agent reply","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentTestMessageResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"},"429":{"description":"Meta hourly test-message limit reached (code rate_limited, Retry-After when known)."}}}},"/v1/accounts/{accountId}/business-agent/events":{"post":{"x-resource-group":"messages","operationId":"sendBusinessAgentEvent","tags":["Business Agent"],"summary":"Send a business event","description":"Tell the agent something happened in your systems (order shipped, document verified) so it messages the consumer about it. The consumer must already have a conversation with the number. Answers 202 with the event id; poll it for the outcome.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to","type","description","payload"],"properties":{"to":{"type":"string","description":"Consumer E.164 phone number.","example":"+34600000000"},"type":{"type":"string","maxLength":256,"example":"order_shipped"},"description":{"type":"string","maxLength":1024},"payload":{"type":"string","maxLength":4096,"description":"JSON string passed to the agent verbatim."}}}}}},"responses":{"202":{"description":"Event accepted","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","example":"accepted"},"agent_event_id":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/events/{eventId}":{"get":{"x-resource-group":"messages","operationId":"getBusinessAgentEvent","tags":["Business Agent"],"summary":"Get a business event status","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"name":"eventId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Event status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAgentEventStatus"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/business-agent/evals":{"get":{"x-resource-group":"messages","operationId":"readBusinessAgentEvals","tags":["Business Agent"],"summary":"Read evaluation data","description":"Without query parameters, lists the evaluation scenarios (`eval_cases`). With `jobId`,\npolls a run started with POST. With `summaryIds`, returns the aggregated insight reports.\nWith `evalIds`, returns per-conversation evaluation details. One of the three at a time.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"},{"name":"jobId","in":"query","required":false,"schema":{"type":"string"}},{"name":"summaryIds","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated summary ids."},{"name":"evalIds","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated evaluation ids."}],"responses":{"200":{"description":"Evaluation data as Meta returns it for the selected read","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}},"post":{"x-resource-group":"messages","operationId":"startBusinessAgentEvalRun","tags":["Business Agent"],"summary":"Start an evaluation run","description":"Simulates the given scenarios against the agent and scores them. Answers 202 with a `job_id` to poll with GET.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessAgentAccountId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["evalCaseIds"],"properties":{"evalCaseIds":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":100}}}}}},"responses":{"202":{"description":"Run started","content":{"application/json":{"schema":{"type":"object","required":["job_id","status"],"properties":{"job_id":{"type":"string"},"status":{"type":"string","example":"RUNNING"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/BusinessAgentForbidden"},"404":{"$ref":"#/components/responses/BusinessAgentNotFound"}}}},"/v1/accounts/{accountId}/tracking-tags":{"get":{"x-resource-group":"ads","operationId":"listTrackingTags","tags":["Tracking Tags"],"x-platforms":["meta","tiktok","google","x","openai","linkedin","pinterest"],"summary":"List tracking tags","description":"Lists the pixels and other measurement tags an ads account can see, so you can inspect or install them.\n\nThe list view omits `code`. Call `getTrackingTag` for the install snippet and full detail.\n\n### Meta and OpenAI Ads\n\nReturns the tracking tags (Meta Pixels, or OpenAI Ads pixels) the connected ads account can see. Meta is platform `metaads` and OpenAI Ads is platform `openaiads`. Platforms without a section below return 501.\n\n- Pass `?adAccountId=act_...` (Meta only) to scope the list to a single ad account.\n- Omit it to list every pixel reachable by the token. The name is then suffixed with the ad account it was discovered on, for disambiguation.\n- `adAccountId` is ignored for OpenAI Ads (one API key maps to exactly one ad account).\n\nThe `accountId` must be the ads SocialAccount created by the Ads add-on connect flow (Meta) or the OpenAI Ads connect flow, not a Facebook/Instagram posting account. Get your Meta `act_...` ids from `GET /v1/ads/accounts`.\n\n### LinkedIn (`linkedinads`)\n\nLists the Insight Tag of each ad account. LinkedIn allows one per ad account; a tag shared with several accounts appears once.\n\n- `adAccountId` is the numeric ad account id or `urn:li:sponsoredAccount:{id}`. Omit it to scan every active ad account the connection can see.\n- The tag `id` IS the partner id the site embeds, so `siteTagId` equals `id`.\n- LinkedIn tags have no name; it is shown as `Insight Tag {id}`.\n\n### Pinterest (platform `pinterestads`)\n\nLists Pinterest tags (conversion tags).\n\n- `adAccountId` is the numeric Pinterest ad account id (no prefix). Omit it to walk every ad account the connection can read (an ad account the user has no Business Access role on is skipped).\n- `id` equals `siteTagId`, the id the site loads with `pintrk('load', id)`.\n\n### TikTok (platform `tiktokads`)\n\nLists TikTok Pixels across the connection's advertisers, or one advertiser with `?adAccountId=<numeric advertiser_id>`.\n\n- `id` is the numeric `pixel_id`.\n- `siteTagId` is the alphanumeric `pixel_code` from Events Manager.\n- Connections authorized before the Pixel Management permission (about 2026-05-28) answer 403 until reconnected.\n\n### X Ads (platform `xads`)\n\nThere is one X Pixel per X ad account.\n\n- `TrackingTag.id` is the ad account id (base36, e.g. `18ce54d4x5t`).\n- `siteTagId` is the pixel id the site embeds.\n- Ad accounts without a pixel are left out.\n- `adAccountId` scopes the list to one ad account.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Ads SocialAccount id (platform `metaads` or `openaiads`)."},{"name":"adAccountId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional, Meta only. Scope to one ad account, e.g. `act_123456789`. Ignored for OpenAI Ads."}],"responses":{"200":{"description":"Tracking tags listed","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["metaads","openaiads","tiktokads","googleads","xads","linkedinads","pinterestads","whopads"]},"tags":{"type":"array","items":{"$ref":"#/components/schemas/TrackingTag"}}}}}}},"400":{"description":"Account platform not supported, or invalid `adAccountId`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the Meta token lacks ads permissions: enable Ads access or reconnect the account.","description":"Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required)."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"The platform does not offer this operation (code `platform_not_supported`); the message names the reason and the alternative."},"502":{"x-summary":"Meta was unreachable or returned an unclassified error: retry the request.","description":"Meta was unreachable or returned an unclassified error (type: platform_error; the raw Meta payload is in platformError). Retryable."}}},"post":{"x-resource-group":"ads","operationId":"createTrackingTag","tags":["Tracking Tags"],"x-platforms":["meta","tiktok","google","x","openai","linkedin","pinterest"],"summary":"Create a tracking tag","description":"Creates a measurement pixel on an ad account and returns the snippet to install on your site.\n\nSupported platforms: Meta (`metaads`), OpenAI Ads (`openaiads`), LinkedIn (`linkedinads`), Pinterest (`pinterestads`), Google Ads (`googleads`), TikTok and X Ads (`xads`). Other platforms return 501.\n\n### Idempotency by platform\n\n| Platform | Idempotent |\n|---|---|\n| Meta | No: each call creates a new pixel |\n| OpenAI Ads | One Zernio pixel per account (a second create answers 409); OpenAI itself makes a new pixel and Conversions API key on every call |\n| LinkedIn | Yes: at most one Insight Tag per ad account |\n| Pinterest | No |\n| Google Ads | Yes: exactly one Google tag per account |\n| TikTok | No: a duplicate name is refused (400) |\n| X Ads | One pixel per ad account; a second answers 409 |\n\nOpenAI Ads, LinkedIn, Pinterest, TikTok and X have no API to delete a tag.\n\nDo not retry blindly on timeout where a call is NOT idempotent.\n\n### Meta\n\nCreates a Meta Pixel on the given ad account (`POST /act_{id}/adspixels`, where `name` is the only input). Returns the created tag including its install `code`.\n\nThe pixel is owned by the Business Manager that owns the ad account. A pixel created on a personal (non-BM) ad account ends up with `ownerBusinessId: null` and can't be shared with other ad accounts.\n\nCreating a Meta pixel does NOT install it. Install the returned `code` snippet on the site, or send events server-side via `POST /v1/ads/conversions`. The check `installed` is derived from `lastFiredTime`.\n\n### OpenAI Ads\n\nCreates an OpenAI pixel AND provisions a Conversions API key for it in the same call. `adAccountId` is required by this endpoint but ignored: one API key maps to exactly one ad account, so there's nothing to select.\n\n- Returns 422 (`FEATURE_NOT_AVAILABLE`) if the ad account isn't enabled for pixel management; contact your OpenAI partner representative to enable it.\n- There is no delete API for OpenAI pixels.\n- If the pixel is created but the Conversions API key provisioning then fails, the pixel is left live on OpenAI (it cannot be cleaned up). The error message names the surviving pixel id and warns against retrying, since a retry would create a second, orphaned pixel.\n\nEach call creates a new pixel, a new Conversions API key and, with `defaultEventType`, a new conversion event setting.\n\n### LinkedIn\n\nCreates the ad account's Insight Tag (`POST /rest/insightTags`).\n\nIdempotent: an ad account holds at most one Insight Tag, so when it already has one that tag is returned and nothing is created. `name` is ignored (LinkedIn tags have no name) and there is no API to delete an Insight Tag.\n\n### Pinterest\n\nCreates a Pinterest tag on the numeric ad account `adAccountId` (`POST /v5/ad_accounts/{id}/conversion_tags`). Returns the tag with Pinterest's `code` snippet. `automaticMatchingFields` switches on automatic enhanced match for those fields.\n\nNOT idempotent, and Pinterest has no dry-run and no delete for tags (DELETE on `conversion_tags/{id}` answers 405). Never retry blindly: list first.\n\n### Google Ads\n\nEvery Google Ads account has exactly one Google tag (`AW-...`), so this is idempotent. `adAccountId` is the 10-digit customer id.\n\n- When the account already tracks conversions, the existing tag is returned (201) and nothing is created.\n- Otherwise a first WEBPAGE conversion action named `name` (category DEFAULT) is created, which is what switches Google's conversion tracking on. The tag is returned with it as its first event.\n\n### TikTok\n\n`POST /pixel/create/` on the advertiser in `adAccountId` (numeric). Names are at most 40 characters with no emoji and must be unique.\n\nTikTok refuses a duplicate name (400), which is its only retry guard. TikTok has no pixel delete API.\n\n### X Ads\n\nCreates the ad account's X Pixel (its UNIVERSAL website tag) with first-party cookies on. `adAccountId` is the X ad account id; `name` is not stored (X pixels have no name).\n\nX allows one pixel per ad account and cannot delete one, so an account that already has a pixel answers 409 without writing anything.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Ads SocialAccount id (platform `metaads` or `openaiads`)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["adAccountId","name"],"properties":{"adAccountId":{"type":"string","description":"Meta ad account id, e.g. `act_123456789`. Required by this endpoint but ignored for OpenAI Ads."},"name":{"type":"string","minLength":1,"maxLength":200},"defaultEventType":{"type":"string","enum":["order_created","lead_created","items_added","contents_viewed","checkout_started","registration_completed","subscription_created","trial_started","appointment_scheduled","page_viewed","app_installed","app_opened"],"description":"OpenAI Ads only (ignored by Meta). When set, also provisions a standard conversion event setting wired to the new pixel, so `goal: conversions` ad creates on `POST /v1/ads/create` have an event to reference immediately."},"automaticMatchingFields":{"type":"array","items":{"type":"string","enum":["em","ph","fn","ln","ge","db","ct","st","zp","country","external_id"]},"description":"Pinterest only (400 elsewhere). Customer data the new tag matches automatically (automatic enhanced match): `em` email, `ph` phone, `fn`/`ln` name, `ge` gender, `db` date of birth, `ct`/`st`/`zp`/`country` location, `external_id`.\n\nPinterest has one switch for the name and one for the location, so `fn` turns on `ln` too and any location code turns on all four.\n"}}}}}},"responses":{"201":{"description":"Tracking tag created","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["metaads","openaiads","tiktokads","googleads","xads","linkedinads","pinterestads","whopads"]},"tag":{"$ref":"#/components/schemas/TrackingTag"}}}}}},"400":{"description":"Invalid body, invalid `adAccountId`, over the per-business pixel cap, or ad account not in a Business Manager."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access, a permission or the account selection is missing: enable access, grant it, or add the ad account to the selection.","description":"Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix it, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"x-summary":"This OpenAI Ads account is not enabled for pixel management: contact your OpenAI partner representative.","description":"OpenAI Ads only: the ad account is not enabled for pixel management. Contact your OpenAI partner representative."},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"The platform does not offer this operation (code `platform_not_supported`); the message names the reason and the alternative."},"502":{"x-summary":"Meta was unreachable or returned an error: list the tracking tags to confirm no pixel was created before retrying.","description":"Meta was unreachable or returned an unclassified error (type: platform_error; the raw Meta payload is in platformError). Creating a pixel is NOT idempotent, so before retrying confirm with GET /v1/accounts/{accountId}/tracking-tags that no pixel was created."}}}},"/v1/accounts/{accountId}/tracking-tags/{tagId}":{"get":{"x-resource-group":"ads","operationId":"getTrackingTag","tags":["Tracking Tags"],"x-platforms":["meta","tiktok","google","x","openai","linkedin","pinterest"],"summary":"Get a tracking tag","description":"Shows one pixel or measurement tag in full, including its install snippet, when it last fired and its conversion events.\n\n### Meta\n\nMeta (platform `metaads`) returns the full tag record including the base-code `code` snippet, `lastFiredTime`, `ownerBusinessId`, `isUnavailable`, etc. Platforms other than those listed here return 501.\n\n### OpenAI Ads\n\nOpenAI Ads (`openaiads`): `tagId` is the pixel's API id (`cds_...`) or its `pixel_id`. OpenAI documents no single-pixel read, so the tag is resolved from the pixel list.\n\n- `code`: the official `oaiq` base code plus `page_viewed`.\n- `events`: the conversion event settings whose source is this pixel.\n- `siteTagId`: the `pixel_id` the site and the Conversions API send.\n- `id`: what event settings reference.\n\n### LinkedIn\n\nLinkedIn (`linkedinads`):\n\n- `code`: LinkedIn's base code.\n- `lastFiredTime`: the most recent callback across the tag's domains (unix seconds, null when it never fired).\n- `events`: the ad account's conversion rules.\n- `siteEvent` and `siteEventId`: set only on rules a page can fire (event-specific Insight Tag rules: not Conversions API rules, no URL match rules).\n- `adAccountId`: picks which ad account's rules to read. It defaults to the account that created the tag.\n\n### Pinterest\n\nPinterest (platform `pinterestads`) returns the tag with Pinterest's own `code` snippet and `lastFiredTime`. Without `adAccountId` Zernio finds the ad account that owns the tag (404 when no readable ad account holds it).\n\n### TikTok\n\nRead from `/pixel/list/?pixel_id=`. `code` is TikTok's `pixel_script` and `events` the pixel events. `lastFiredTime` is not available on TikTok. Without `adAccountId` the connection's advertisers are searched.\n\n### X Ads\n\nX Ads (platform `xads`): `tagId` is the X ad account id. An ad account without a pixel answers 400.\n\n- `siteTagId`: the pixel id.\n- `code`: the X Pixel base code.\n- `events`: the conversion events the site can fire, each with `siteEventId` = `tw-<pixel>-<event>` (also the `event_id` of the X Conversions API).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"tagId","in":"path","required":true,"schema":{"type":"string"},"description":"Tag id (`TrackingTag.id`)."},{"name":"adAccountId","in":"query","required":false,"schema":{"type":"string"},"description":"Scopes the lookup on platforms whose tag ids live inside an ad account. Ignored elsewhere."}],"responses":{"200":{"description":"Tracking tag fetched","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["metaads","tiktokads","googleads","xads","openaiads","linkedinads","pinterestads","whopads"]},"tag":{"$ref":"#/components/schemas/TrackingTag"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the Meta token lacks ads permissions: enable Ads access or reconnect the account.","description":"Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required)."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"The platform does not offer this operation (code `platform_not_supported`); the message names the reason and the alternative."},"502":{"x-summary":"Meta was unreachable or returned an unclassified error: retry the request.","description":"Meta was unreachable or returned an unclassified error (type: platform_error; the raw Meta payload is in platformError). Retryable."}}},"patch":{"x-resource-group":"ads","operationId":"updateTrackingTag","tags":["Tracking Tags"],"x-platforms":["meta","tiktok","google","x","openai","linkedin","pinterest"],"summary":"Update a tracking tag","description":"Changes a pixel's settings, such as its name or automatic matching, on platforms that allow edits.\n\nPartial-update a pixel. Returns the re-fetched canonical tag. Whitelisted fields (at least one is required):\n\n- `name` (rename)\n- `enableAutomaticMatching`\n- `automaticMatchingFields`\n- `firstPartyCookieStatus`\n- `dataUseSetting`\n\nMeta only (platform `metaads`); other platforms return 501, except where noted below.\n\nThere is no DELETE: Meta has no API to delete a pixel. To stop using one, unshare it from your ad accounts (`DELETE .../tracking-tags/{tagId}/shared-accounts`) or disable it in Events Manager.\n\n### Per-platform support\n\n- Google Ads (`googleads`): see below.\n- LinkedIn (`linkedinads`): only `firstPartyCookieStatus` (`first_party_cookie_enabled` or `first_party_cookie_disabled`), which sets the tag's first-party tracking. It applies to every ad account using the tag. `empty` answers 400: LinkedIn has no unset state.\n- TikTok: see below.\n- X Ads (platform `xads`): only `firstPartyCookieStatus` (`first_party_cookie_enabled` or `first_party_cookie_disabled`), which sets the pixel's first-party cookie setting. X has no API to rename or delete a pixel.\n- Pinterest (platform `pinterestads`): 501, see below.\n- OpenAI Ads: 501, see below.\n\n### Google Ads\n\nThe only writable tag setting is `autoTagging` (the account's gclid auto-tagging, without which the tag cannot attribute conversions to ad clicks).\n\nGoogle rejects every write to `conversion_tracking_setting` for our developer token (`SERVICE_ACCESS_DENIED`), so the tag id and cross-account ownership stay managed in the Google Ads UI.\n\n### TikTok\n\n- `name`.\n- `enableAutomaticMatching` + `automaticMatchingFields`, folded onto TikTok's five switches: em, ph, fn/ln, ct/st/zp/country, external_id. ge and db answer 400.\n- First-party cookies via `enableFirstPartyCookies` or `firstPartyCookieStatus` (enabled or disabled).\n\nTikTok has no pixel delete: the endpoint is absent from its API and `POST /pixel/delete/` answers 404.\n\n### Pinterest\n\nPinterest API v5 only creates, lists and reads tags; it has no endpoint to edit a tag. Its spec lists only POST/GET on `conversion_tags` and GET on `conversion_tags/{id}`, and PATCH or PUT on `conversion_tags/{id}` answer 405 \"Method not allowed\".\n\nSet enhanced match at creation (`automaticMatchingFields`), or rename a tag and change its enhanced match settings in Pinterest Ads Manager.\n\n### OpenAI Ads\n\nIts API has no pixel update or delete route (`POST`/`PATCH`/`PUT`/`DELETE /v1/conversions/pixels/{id}` answer 405 \"Invalid method\"). Rename a pixel in OpenAI Ads Manager.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"tagId","in":"path","required":true,"schema":{"type":"string"},"description":"Pixel id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"At least one updatable field is required; the route returns 400 if the body is empty or names a field the tag's platform cannot update.","properties":{"adAccountId":{"type":"string","description":"Scopes the lookup on platforms whose tag ids live inside an ad account. Ignored elsewhere."},"name":{"type":"string","minLength":1,"maxLength":200},"enableAutomaticMatching":{"type":"boolean","description":"Meta Advanced Matching toggle (`enable_automatic_matching`)."},"automaticMatchingFields":{"type":"array","description":"Which user fields Advanced Matching may collect. Meta's\nterse codes: em=email, ph=phone, fn=first name, ln=last\nname, ge=gender, db=date of birth, ct=city, st=state,\nzp=zip.\n","items":{"type":"string","enum":["em","ph","fn","ln","ge","db","ct","st","zp","country","external_id"]}},"firstPartyCookieStatus":{"type":"string","enum":["empty","first_party_cookie_disabled","first_party_cookie_enabled"]},"dataUseSetting":{"type":"string","enum":["advertising_and_analytics","analytics_only","empty"]},"enableFirstPartyCookies":{"type":"boolean","description":"First-party cookie on or off (TikTok, LinkedIn). Platform-neutral alternative to `firstPartyCookieStatus`."},"autoTagging":{"type":"boolean","description":"Google Ads: turn gclid auto-tagging on or off for the ad account."}}}}}},"responses":{"200":{"description":"Tracking tag updated (re-fetched canonical state)","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["metaads","tiktokads","googleads","xads","openaiads","linkedinads","pinterestads","whopads"]},"tag":{"$ref":"#/components/schemas/TrackingTag"}}}}}},"400":{"x-summary":"The body is invalid, for example no fields were sent, or Meta rejected it: fix the request and resend.","description":"Invalid body (e.g. no fields supplied) or Meta validation failure."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access, a permission or the account selection is missing: enable access, grant it, or add the ad account to the selection.","description":"Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"The platform does not offer this operation (code `platform_not_supported`); the message names the reason and the alternative."},"502":{"x-summary":"Meta was unreachable or returned an unclassified error: retry the request.","description":"Meta was unreachable or returned an unclassified error (type: platform_error; the raw Meta payload is in platformError). Retryable."}}}},"/v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts":{"get":{"x-resource-group":"ads","operationId":"listTrackingTagSharedAccounts","tags":["Tracking Tags"],"x-platforms":["meta","linkedin","tiktok"],"summary":"List accounts it is shared with","description":"Lists the other ad accounts a pixel is shared with.\n\nMeta (`metaads`) and LinkedIn (`linkedinads`); other platforms return 501.\n\nLinkedIn (`linkedinads`): the ad accounts this connection can see that hold access to the\nInsight Tag; the role (`FULL` or `USE_ONLY`) is appended to `name`. LinkedIn exposes\npermissions per ad account only, so accounts the connection cannot see are not listed.\n\nTikTok (`tiktokads`): the advertisers linked to the pixel in its Business Center\n(`/bc/pixel/link/get/`); a pixel outside Business Center answers 400.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"tagId","in":"path","required":true,"schema":{"type":"string"},"description":"Pixel id."}],"responses":{"200":{"description":"Shared ad accounts listed","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["metaads","linkedinads"]},"sharedAccounts":{"type":"array","items":{"$ref":"#/components/schemas/SharedAdAccount"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the Meta token lacks ads permissions: enable Ads access or reconnect the account.","description":"Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required)."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"The platform does not offer this operation (code `platform_not_supported`); the message names the reason and the alternative."},"502":{"x-summary":"Meta was unreachable or returned an unclassified error: retry the request.","description":"Meta was unreachable or returned an unclassified error (type: platform_error; the raw Meta payload is in platformError). Retryable."}}},"post":{"x-resource-group":"ads","operationId":"addTrackingTagSharedAccount","tags":["Tracking Tags"],"x-platforms":["meta","linkedin","tiktok"],"summary":"Share with an ad account","description":"Shares a pixel with another ad account so its campaigns and audiences can use it. Meta, LinkedIn and TikTok; other platforms return 501.\n\n### Meta\n\nRequires that you administer both the pixel's owning Business Manager and the target ad account. A pixel on a personal (non-BM) ad account can't be shared (Meta will reject the call).\n\n### LinkedIn\n\nLinkedIn (`linkedinads`) grants `USE_ONLY` access from the ad account that created the tag, so the target can use the tag and its conversions but cannot edit or reshare it.\n\n- `adAccountId` is the numeric LinkedIn ad account id.\n- An ad account uses one Insight Tag at a time, so a target that already has one answers 400.\n\n### TikTok\n\nLinks the pixel to an advertiser through Business Center (`/bc/pixel/link/update/`, `adAccountId` = numeric advertiser_id).\n\nOnly a pixel that is an asset of a Business Center this connection manages can be shared. Otherwise the answer is 400 asking to transfer it to Business Center first.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"tagId","in":"path","required":true,"schema":{"type":"string"},"description":"Pixel id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["adAccountId"],"properties":{"adAccountId":{"type":"string","description":"Ad account to share with, e.g. `act_123456789`."}}}}}},"responses":{"201":{"description":"Tracking tag shared with the ad account","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["metaads","linkedinads"]},"ok":{"type":"boolean"}}}}}},"400":{"x-summary":"The body or ad account ID is invalid, or Meta rejected the share: fix the request and resend.","description":"Invalid body / `adAccountId`, or Meta rejected the share (e.g. personal ad account)."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is blocked: enable the Ads add-on, reconnect Meta for ads permissions, or select the ad account.","description":"Forbidden. One of:\n\n- Ads access required (Ads add-on on legacy plans, included on usage-based plans).\n- The Meta token lacks ads permissions (reconnect required).\n- Code `ad_account_not_selected`: the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"The platform does not offer this operation (code `platform_not_supported`); the message names the reason and the alternative."},"502":{"x-summary":"Meta was unreachable or returned an unclassified error: retry the request.","description":"Meta was unreachable or returned an unclassified error (type: platform_error; the raw Meta payload is in platformError). Retryable."}}},"delete":{"x-resource-group":"ads","operationId":"removeTrackingTagSharedAccount","tags":["Tracking Tags"],"x-platforms":["meta","linkedin","tiktok"],"summary":"Stop sharing with an account","description":"Stops sharing a pixel with an ad account.\n\n`adAccountId` may be passed as a query parameter (recommended) or as a\nJSON body field for clients that can send DELETE bodies. Meta and\nLinkedIn; other platforms return 501.\n\nLinkedIn (`linkedinads`): revokes the ad account's access. Zernio answers 400 instead of\nrevoking the last ad account that holds the tag: LinkedIn accepts that call and the tag\nis orphaned (verified live).\n\nTikTok: unlinks through Business Center (`/bc/pixel/link/update/` with `UNLINK`).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"tagId","in":"path","required":true,"schema":{"type":"string"},"description":"Pixel id."},{"name":"adAccountId","in":"query","required":false,"schema":{"type":"string"},"description":"Ad account to unshare, e.g. `act_123456789`. May also be sent in the JSON body."}],"responses":{"204":{"description":"Ad account unshared (no content)."},"400":{"description":"`adAccountId` missing (neither query nor body), or Meta rejected the unshare."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access, a permission or the account selection is missing: enable access, grant it, or add the ad account to the selection.","description":"Forbidden.\n\n- Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).\n- Code `ad_account_not_selected`: the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix `ad_account_not_selected`, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"The platform does not offer this operation (code `platform_not_supported`); the message names the reason and the alternative."},"502":{"x-summary":"Meta was unreachable or returned an unclassified error: retry the request.","description":"Meta was unreachable or returned an unclassified error (type: platform_error; the raw Meta payload is in platformError). Retryable."}}}},"/v1/accounts/{accountId}/tracking-tags/{tagId}/install":{"post":{"x-resource-group":"ads","operationId":"installTrackingTagOnStore","tags":["Tracking Tags"],"x-platforms":["meta","tiktok","google","x","openai","linkedin","pinterest","whop","shopify","wordpress","wix","webflow"],"summary":"Install on a Shopify, WordPress, Wix or Webflow site","description":"Installs a pixel on a connected Shopify store or WordPress, Wix or Webflow site, so store visits and purchases are reported without editing the theme.\n\n### Shopify (Meta pixel)\n\nZernio puts the Meta pixel on the store's storefront and checkout through its Shopify web pixel (a Shopify app pixel, no theme edits). The store sends these events to the pixel, each with an event id:\n\n- PageView\n- ViewContent\n- AddToCart\n- Search\n- InitiateCheckout\n- AddPaymentInfo\n- Purchase (with value, currency, content_ids and contents)\n\nPurchase uses `shopify_order_{orderId}` as its event id. A Conversions API Purchase you send for the same order with that `eventId` is deduplicated by Meta.\n\n### Idempotency and identifiers\n\nA store runs one Zernio web pixel holding one tag per platform, so the call is idempotent:\n\n- Calling it again updates the install.\n- Installing a different tag of the same platform replaces the previous one (reported in `replacedTagId`).\n- Other platforms' tags are kept.\n\nEvents respect the store's customer privacy settings (marketing consent).\n\n- `accountId`: the Meta ads account that owns the pixel (`tagId`).\n- `storeAccountId`: the Shopify account.\n\n### OpenAI Ads on Shopify\n\nEach event is sent through OpenAI's documented image tag (`GET https://bzr.openai.com/v1/sdk/events`) as:\n\n- `page_viewed`\n- `contents_viewed`\n- `items_added`\n- `checkout_started`\n- `order_created`\n- custom events `search` and `addpaymentinfo` (lowercase, so a Conversions API Search/AddPaymentInfo with the same event id deduplicates)\n\nAmounts are sent in the currency's minor unit. The landing page's `oppref` click id is kept in the `__oppref` cookie for 30 days and sent with every event.\n\nThe image tag cannot carry the `__obref` browser id (OpenAI rejects the parameter), and the search text is never sent. On WordPress the widget holds the official `oaiq` base code and a `page_viewed` call.\n\n### Whop on Shopify\n\nFor Whop (`whopads`, `tagId` = the Whop account id `biz_...`), events are posted to Whop's conversions endpoint (`https://t.whop.tw/conversions`) the way Whop's own Shopify pixel does:\n\n- `page`\n- `view_content`\n- `add_to_cart`\n- `purchase` (with value and currency)\n- custom `shopify_search_submitted`, `shopify_checkout_started` and `shopify_payment_info_submitted`\n\nEach carries Whop's `shopify:<event>:<id>` event id, so a store that also runs Whop's own pixel reports each event once. The visitor id is kept in Whop's `_wuid` cookie for two years.\n\nWhop records purchases itself only for checkouts on Whop, so Shopify orders are reported here. On WordPress the widget holds the official snippet with `whop.setScope` and `whop.track(\"page\")`.\n\n### Reconnect and unsupported platforms\n\n- 409 `reconnect_required`: the store was connected before pixel support and must re-approve the Zernio app. Send the merchant to `details.authUrl` (the Shopify account id stays the same).\n- 501: the platform has no install path.\n\n### WordPress\n\nHere `storeAccountId` is a connected WordPress.com or self-hosted site. Zernio adds a Custom HTML widget with the Meta pixel base code (fbevents.js, `init`, `PageView`) to a widget area of the active theme.\n\nIt uses a footer area when there is one, else the first active area; pass `sidebarId` to choose. It then reads the widget back to confirm WordPress kept the `<script>` tag.\n\nThe widget carries a Zernio marker, so the call is idempotent per pixel: repeating it updates or moves the same widget. Pixel code the site owner pasted by hand is never touched. Several pixels can run side by side (one widget each).\n\nWhen the site cannot run the pixel, nothing is left behind and the call answers 422 `tracking_tag_install_blocked` with `details.reason`:\n\n- `insufficient_permissions`: the connected user lacks `edit_theme_options` (needs Administrator).\n- `scripts_stripped`: WordPress removed the script (the user lacks `unfiltered_html`, e.g. a multisite admin who is not a Super Admin, or `DISALLOW_UNFILTERED_HTML` is set).\n- `wordpress_com_plan`: a WordPress.com plan that strips scripts (plans without plugins).\n- `no_widget_areas`: the theme has no widget areas (block themes such as Twenty Twenty-Five).\n- `widgets_api_unavailable`: no widgets REST API (WordPress older than 5.8, or disabled).\n\nThe `error` message names the manual alternative (Meta's official WordPress plugin).\n\nWith `verifyHomepage` (default true) the homepage is fetched afterwards and `homepageCheck` says whether the pixel is visible. `not_found` can be a stale page cache; the widget read-back is authoritative.\n\n### LinkedIn\n\nFor `linkedinads`, Shopify sends every page view to the Insight Tag. It also sends each store event that has an enabled event-specific Insight Tag conversion rule of the matching type:\n\n- view_content = VIEW_CONTENT\n- add_to_cart = ADD_TO_CART\n- search = SEARCH\n- initiate_checkout = START_CHECKOUT\n- add_payment_info = ADD_BILLING_INFO\n- purchase = PURCHASE\n\nEach conversion carries the event id. Purchase uses `shopify_order_{orderId}`, so a Conversions API event sent to a separate CONVERSIONS_API rule with that `eventId` is deduplicated by LinkedIn.\n\nConversions API rules cannot be fired from a page, and no rule is created for you. The `li_fat_id` click id is read from the landing URL and kept in a first-party cookie for 30 days. WordPress gets LinkedIn's base code, which records page views.\n\n### Pinterest\n\nFor platform `pinterestads`, Shopify sends these events to the tag: `pagevisit`, `viewcontent`, `addtocart`, `search`, `initiatecheckout`, `addpaymentinfo` and `checkout`.\n\nEach carries `event_id` (Purchase: `shopify_order_{orderId}`, for dedup with the Pinterest Conversions API), value, currency, order quantity and line items, plus the `epik` click id kept in the `_epik` cookie.\n\nWordPress gets Pinterest's base code (core.js, `load`, `page`) with a `pagevisit` event. The manual fallback is the official Pinterest for WooCommerce plugin (WooCommerce stores).\n\n### Wix\n\nHere `storeAccountId` is a connected Wix site. Zernio's Wix app embeds one script on the site that loads each installed tag's base code (the same code WordPress gets), so on Wix each tag records page views.\n\nWix changes pages without reloading. Later page views are recorded again on Wix's own page-view event for Meta, TikTok, Google, Pinterest, OpenAI and Whop; LinkedIn and X count the first page of each visit.\n\nLike Shopify, the site holds one tag per platform: installing a different tag of the same platform replaces it (`replacedTagId`) and other platforms' tags are kept.\n\nThe script is an Advertising script, so it runs only for visitors who accept advertising cookies when the site shows a cookie banner.\n\nSites connected before pixel support answer 409 `reconnect_required` until the owner approves the Zernio app's new permission (`details.authUrl`, or Apps > Manage Apps in the Wix dashboard).\n\n### Webflow\n\nHere `storeAccountId` is a Webflow site connected with \"Connect with Webflow\" (`GET /v1/connect/webflow`). Zernio applies one script to the site's custom code that loads each tag's base code, one tag per platform, as on Wix.\n\nWebflow publishes custom code only with the site, so the install answers `publishRequired: true` and the tags fire after the site's next publish (Zernio never publishes it).\n\nA site connected with a site token answers 409 `reconnect_required` with `details.authUrl` to connect it with the app (the account id stays the same).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"tagId","in":"path","required":true,"schema":{"type":"string"},"description":"Tag id (`TrackingTag.id`)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["storeAccountId"],"properties":{"storeAccountId":{"type":"string","description":"The connected Shopify (`shopify`), WordPress (`wordpress`), Wix (`wix`) or Webflow (`webflow`) account id."},"adAccountId":{"type":"string","description":"Scopes the tag lookup on platforms whose tag ids live inside an ad account. Ignored elsewhere."},"sidebarId":{"type":"string","description":"WordPress only: widget area to use (see `install.preflight.sidebars` from GET). Defaults to a footer area."},"verifyHomepage":{"type":"boolean","default":true,"description":"WordPress only: fetch the homepage afterwards and report `homepageCheck`."}}}}}},"responses":{"200":{"description":"Pixel installed on the store","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["metaads","tiktokads","googleads","xads","openaiads","linkedinads","pinterestads","whopads"]},"install":{"allOf":[{"$ref":"#/components/schemas/StorePixelInstall"},{"type":"object","properties":{"replacedTagId":{"type":["string","null"],"description":"Shopify, Wix and Webflow only: the pixel this install replaced on the store, if any."},"sidebarName":{"type":"string","description":"WordPress only: name of the widget area used."},"created":{"type":"boolean","description":"WordPress only: false when an existing Zernio widget was updated."},"homepageCheck":{"type":"string","enum":["found","not_found","unreachable","skipped"],"description":"WordPress only: whether the pixel appeared in the homepage HTML. `not_found` can be a stale page cache."}}}]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the Meta token lacks ads permissions: enable Ads access or reconnect the account.","description":"Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required)."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/StoreReconnectRequired"},"422":{"x-summary":"The WordPress site cannot run the pixel, and nothing was left installed on it.","description":"WordPress only: the site cannot run the pixel and nothing was left on it. Code `tracking_tag_install_blocked`; the reason is in `details.reason`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What blocked the install and the manual alternative."},"code":{"type":"string","enum":["tracking_tag_install_blocked"]},"details":{"type":"object","properties":{"reason":{"$ref":"#/components/schemas/TrackingTagInstallBlockedReason"}}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"The platform does not offer this operation (code `platform_not_supported`); the message names the reason and the alternative."},"502":{"x-summary":"The platform was unreachable or returned an unclassified error: on WordPress, check the site with a GET before retrying.","description":"Meta, Shopify or the WordPress site was unreachable or returned an unclassified error. On WordPress a write may have completed; call GET before retrying."}}},"get":{"x-resource-group":"ads","operationId":"getTrackingTagStoreInstall","tags":["Tracking Tags"],"x-platforms":["meta","tiktok","google","x","openai","linkedin","pinterest","shopify","wordpress","wix","webflow"],"summary":"Get store install status","description":"Shows whether a tracking tag is installed on your Shopify store or WordPress, Wix or Webflow site, and whether a WordPress install would be blocked.\n\n### Shopify\n\nWhether this tag is the one the Shopify store fires for its platform.\n\n- `installedTagId` names the tag of that platform the store currently fires, which can be a different tag.\n- `tags` lists every Zernio tag on the store (all platforms).\n\n### WordPress\n\nWhether the Zernio widget for this pixel is live (in an active widget area, script intact).\n\n- A read-only `preflight` returns the theme's widget areas and, when an install would be blocked, the `reason` POST would return.\n- `tags` lists every Zernio widget on the site (all platforms, with `active`).\n\nThe preflight reads capabilities only, so `ready: true` is not a guarantee. `DISALLOW_UNFILTERED_HTML` or a multisite admin who is not a Super Admin still strips the script, which POST detects.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"tagId","in":"path","required":true,"schema":{"type":"string"},"description":"Tag id (`TrackingTag.id`)."},{"name":"storeAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"The connected Shopify, WordPress, Wix or Webflow account id."},{"name":"adAccountId","in":"query","required":false,"schema":{"type":"string"},"description":"Scopes the tag lookup on platforms whose tag ids live inside an ad account."}],"responses":{"200":{"description":"Install status","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["metaads","tiktokads","googleads","xads","openaiads","linkedinads","pinterestads","whopads"]},"install":{"allOf":[{"$ref":"#/components/schemas/StorePixelInstall"},{"type":"object","properties":{"preflight":{"type":"object","description":"WordPress only.","properties":{"ready":{"type":"boolean","description":"True when POST should be able to install."},"reason":{"type":["string","null"],"description":"A TrackingTagInstallBlockedReason when an install would be blocked, else null."},"sidebars":{"type":"array","description":"Active widget areas of the theme.","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}}}}]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads access required (Ads add-on on legacy plans, included on usage-based plans)."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/StoreReconnectRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"The platform does not offer this operation (code `platform_not_supported`); the message names the reason and the alternative."}}},"delete":{"x-resource-group":"ads","operationId":"removeTrackingTagFromStore","tags":["Tracking Tags"],"x-platforms":["meta","tiktok","google","x","openai","linkedin","pinterest","shopify","wordpress","wix","webflow"],"summary":"Remove from a Shopify, WordPress, Wix or Webflow site","description":"Removes a tracking tag from your Shopify store or WordPress, Wix or Webflow site, leaving other platforms' tags and hand-added pixel code in place.\n\n### Behavior\n\n- Idempotent: nothing installed returns 200 with `installed: false`.\n- If the store fires a different tag of the same platform, nothing is removed and the call answers 409 `invalid_resource_state`.\n\n### Per store\n\n- **Shopify**: other platforms' tags stay. The web pixel itself is deleted once no tag remains.\n- **Wix**: works the same way, and the site's Zernio script is disabled once no tag remains.\n- **Webflow**: the Zernio script leaves the site's custom code once no tag remains, live after the next publish.\n- **WordPress**: deletes every widget Zernio created for this pixel and reports how many in `removed` (0 when nothing was installed). Pixel code added by hand is left alone.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"tagId","in":"path","required":true,"schema":{"type":"string"},"description":"Tag id (`TrackingTag.id`)."},{"name":"storeAccountId","in":"query","required":true,"schema":{"type":"string"},"description":"The connected Shopify, WordPress, Wix or Webflow account id."},{"name":"adAccountId","in":"query","required":false,"schema":{"type":"string"},"description":"Scopes the tag lookup on platforms whose tag ids live inside an ad account."}],"responses":{"200":{"description":"Pixel removed (or was not installed)","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["metaads","tiktokads","googleads","xads","openaiads","linkedinads","pinterestads","whopads"]},"install":{"allOf":[{"$ref":"#/components/schemas/StorePixelInstall"},{"type":"object","properties":{"removed":{"type":"integer","description":"WordPress only: number of Zernio widgets deleted."}}}]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads access required (Ads add-on on legacy plans, included on usage-based plans)."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"x-summary":"The store fires a different pixel or must re-approve the Zernio app: use `details.authUrl` when it is returned.","description":"The store fires a different pixel (code `invalid_resource_state`), or the store must re-approve the Zernio app (code `reconnect_required`, see `details.authUrl`)."},"501":{"description":"The platform does not offer this operation (code `platform_not_supported`); the message names the reason and the alternative."}}}},"/v1/accounts/{accountId}/tracking-tags/{tagId}/events":{"get":{"x-resource-group":"ads","operationId":"listTrackingTagEvents","tags":["Tracking Tags"],"x-platforms":["meta","google","tiktok","linkedin","x","openai","pinterest"],"summary":"List conversion events","description":"Lists the conversion events tied to a tracking tag, such as Google conversion actions or Meta custom conversions.\n\nIt covers platforms where each conversion is its own object:\n\n- Google conversion actions\n- LinkedIn conversion rules\n- X web event tags\n- OpenAI event settings\n- TikTok pixel events\n- Meta custom conversions\n- Pinterest advertiser defined events\n\n### OpenAI Ads\n\nThe account's conversion event settings whose source is this pixel.\n\n- `siteEventId` is the event name the site sends (a standard event such as `order_created`, or the lowercase custom event name).\n- `clickWindowDays` is the click attribution window and `viewWindowDays` the view-through window (0 = off).\n\n### LinkedIn (`linkedinads`)\n\nThe conversion rules of the ad account (`adAccountId`, default the account that created the tag), including Conversions API and URL-match rules.\n\n- `siteEventId` (the rule id a page fires) is set only on event-specific Insight Tag rules.\n- `defaultValue`/`currency` come from the rule value.\n- `clickWindowDays`/`viewWindowDays` come from its post-click and view-through windows.\n\n### Meta\n\nThe pixel's custom conversions. Meta keeps them per AD ACCOUNT (a pixel has no custom conversions edge). So the list reads `adAccountId` (default: the pixel's owner ad account) and keeps the conversions whose pixel is this one.\n\nArchived conversions are included with `status: archived`. `urlContains` and `siteEvent` are parsed from Meta's rule.\n\n### Google Ads (`googleads`)\n\nThe enabled WEBPAGE conversion actions of the account. `siteEventId` is the conversion label (the part after `AW-.../` in `send_to`). Value settings, lookback windows, `primary` and `countingType` are returned.\n\nArchived (removed) actions are listed with status `REMOVED`. Imported (GA4, upload, app) actions are not events of the tag.\n\n### Pinterest (platform `pinterestads`)\n\nThe ad account's advertiser defined events: custom event names mapped to a standard type (`type`, e.g. `SIGNUP`). They belong to the ad account, so every tag on it shares them.\n\n`id`, `name` and `siteEventId` are all the event name, which the site sends as `pintrk('track', '<name>')` or the Conversions API sends as `event_name`.\n\nStandard events (`pagevisit`, `checkout`...) need no object and are not listed.\n\n### TikTok\n\nThe pixel's events from `/pixel/list/`. TikTok refreshes this list every 2 to 4 hours, so a just-created event can be missing. `siteEventId` is the `ttq.track()` name the site fires.\n\n### X Ads (platform `xads`)\n\nThe ad account's web event tags the site can fire.\n\nEvents X auto-creates with the pixel (site visits, landing page views, one per standard type) share the pixel id and cannot be fired one by one, so they are left out. They still appear in stats.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"tagId","in":"path","required":true,"schema":{"type":"string"},"description":"Tag id (`TrackingTag.id`)."},{"name":"adAccountId","in":"query","required":false,"schema":{"type":"string"},"description":"Scopes the lookup on platforms whose tag ids live inside an ad account."}],"responses":{"200":{"description":"Conversion events listed","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/TrackingTagEvent"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads access required, or the platform token lacks the permission (reconnect required)."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"The platform has no conversion-event objects (code `platform_not_supported`); the message names the alternative."}}},"post":{"x-resource-group":"ads","operationId":"createTrackingTagEvent","tags":["Tracking Tags"],"x-platforms":["meta","google","tiktok","linkedin","x","openai","pinterest"],"summary":"Create a conversion event","description":"Creates a conversion event on a tracking tag, such as a purchase or lead, so ads can measure and optimise toward it.\n\nPass the platform's own event type in `type` (e.g. Google `PURCHASE`, LinkedIn `ADD_TO_CART`, X `CHECKOUT_INITIATED`) or a neutral `siteEvent` the platform maps to its closest type.\n\nEach platform stores a subset of the optional fields. Sending one it does not store answers 400 naming the supported fields.\n\nNOT idempotent unless noted per platform: do not retry blindly.\n\n### OpenAI Ads\n\nCreates a conversion event setting on the pixel (`POST /conversions/event_settings`, source = the pixel). Accepts `name`, `type` and `siteEvent` only.\n\n`type` is a standard event or, for anything else, the custom event name itself (1 to 64 letters, digits, underscores or dashes; stored lowercase). Standard events: `order_created`, `lead_created`, `items_added`, `contents_viewed`, `checkout_started`, `registration_completed`, `subscription_created`, `trial_started`, `appointment_scheduled`, `page_viewed`, `app_installed`, `app_opened`.\n\n`siteEvent` maps `search` and `add_payment_info` to the custom events `search` and `addpaymentinfo`, the names Zernio's Shopify pixel sends.\n\nThe click attribution window is 30 days, the only value OpenAI documents. Only standard events can be a conversions campaign's optimization goal.\n\n### LinkedIn (`linkedinads`)\n\nCreates an event-specific Insight Tag conversion rule (no URL match rules), the kind a page or the Shopify pixel fires by id.\n\n- `type` is a LinkedIn conversion type (e.g. `PURCHASE`, `ADD_TO_CART`, `START_CHECKOUT`, `LEAD`).\n- `siteEvent` maps to `KEY_PAGE_VIEW`, `VIEW_CONTENT`, `ADD_TO_CART`, `SEARCH`, `START_CHECKOUT`, `ADD_BILLING_INFO` or `PURCHASE`.\n- `defaultValue` needs `currency` (the ad account currency) and is a fallback: a value sent with the event wins.\n- Click and view windows are in days (LinkedIn validates them: the docs list 1, 7 and 30, and rules with 90 exist).\n\nStores name, type, siteEvent, enabled, defaultValue, currency, clickWindowDays, viewWindowDays. Not idempotent.\n\n### Meta\n\nCreates a custom conversion on `adAccountId` (default: the pixel's owner ad account). Accepts:\n\n- `name`\n- `type` (Meta `custom_event_type`: `PURCHASE`, `LEAD`, `ADD_TO_CART`, `COMPLETE_REGISTRATION`, `OTHER`...)\n- `siteEvent`\n- `urlContains`\n- `defaultValue` (in the ad account currency)\n\nThe rule matches the standard event of `siteEvent` (or of `type`), plus `urlContains` when given. `urlContains` alone matches page views on that URL. `type: OTHER` needs `siteEvent` or `urlContains`.\n\nIdempotent by name: an active conversion with the same name on this pixel is returned instead of a duplicate. Meta caps custom conversions per ad account; the cap answers 400.\n\n### Google Ads (`googleads`)\n\nCreates a WEBPAGE conversion action. `type` is a ConversionActionCategory (e.g. `PURCHASE`, `SIGNUP`, `DEFAULT`).\n\n`siteEvent` maps page_view, add_to_cart, initiate_checkout and purchase. view_content, search and add_payment_info answer 400 (Google has no category for them).\n\nStored fields: name, type, defaultValue, currency, alwaysUseDefaultValue, clickWindowDays (1 to 90), viewWindowDays (1 to 30), primary, countingType, enabled.\n\nActions are created enabled (`enabled: false` answers 400); Google blocks the HIDDEN status on WEBPAGE actions. Names are unique per account, so a replay answers 400 (DUPLICATE_NAME) instead of creating a second one.\n\n### Pinterest (platform `pinterestads`)\n\nCreates an advertiser defined event on the tag's ad account. Fields:\n\n- `name`: 1-100 letters, digits, `_` or `-`, case-insensitive, max 15 per ad account\n- `type` or `siteEvent`: `type` is one of Pinterest's optimizable types: SIGNUP, ADD_TO_CART, LEAD, CHECKOUT, SUBSCRIBE, ADD_TO_WISHLIST, ADD_PAYMENT_INFO, INITIATE_CHECKOUT, CONTACT, CUSTOMIZE_PRODUCT, FIND_LOCATION, SCHEDULE, SUBMIT_APPLICATION, START_TRIAL, PAGE_VISIT, VIEW_CATEGORY, VIEW_CONTENT, SEARCH, WATCH_VIDEO\n\nA duplicate name answers 400.\n\n### TikTok\n\nCalls `POST /pixel/event/create/`. `type` is a TikTok pixel event type (SHOPPING, ON_WEB_CART, ON_WEB_DETAIL, INITIATE_ORDER, ADD_BILLING, ON_WEB_SEARCH, PAGE_VIEW, ON_WEB_REGISTER, FORM, ...), or pass `siteEvent`.\n\nStores `name` (at most 40 characters), `defaultValue` and `currency` (USD, JPY or INR only).\n\nTikTok returns no id: the new event is read back from the pixel. While TikTok's listing has not refreshed, the response carries an empty `id` and `status: pending`.\n\n### X Ads (platform `xads`)\n\nCreates a web event tag. Fields:\n\n- `name`\n- `type` or `siteEvent`. `type` is an X enum: ADDED_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, CHECKOUT_INITIATED, CONTENT_VIEW, CUSTOM, DOWNLOAD, INSTALL, LANDING_PAGE_VIEW, LOGIN, PRODUCT_CUSTOMIZATION, PURCHASE, SEARCH, SESSION, SIGN_UP, SITE_VISIT, START_TRIAL, SUBSCRIBE\n- `clickWindowDays`: 1, 7, 14, 30, 60 or 90; default 30\n- `viewWindowDays`: 0, 1, 7, 14, 30, 60 or 90, at most the click window; default 1\n\nRetargeting is enabled, as in Events Manager.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"tagId","in":"path","required":true,"schema":{"type":"string"},"description":"Tag id (`TrackingTag.id`)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TrackingTagEventInput"},{"type":"object","required":["name"]}]}}}},"responses":{"201":{"description":"Conversion event created","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string"},"event":{"$ref":"#/components/schemas/TrackingTagEvent"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access, a permission or the account selection is missing: enable access, grant it, or add the ad account to the selection.","description":"Ads access required, or the platform token lacks the permission (reconnect required).\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection), or use a connection that has it selected."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"The platform cannot create conversion events through its API (code `platform_not_supported`)."}}}},"/v1/accounts/{accountId}/tracking-tags/{tagId}/events/{eventId}":{"patch":{"x-resource-group":"ads","operationId":"updateTrackingTagEvent","tags":["Tracking Tags"],"x-platforms":["meta","google","tiktok","linkedin","x","openai","pinterest"],"summary":"Update a conversion event","description":"Changes a conversion event's settings, such as its name or default value, where the platform allows edits.\n\nPartial update; at least one field. A field the platform does not store answers 400.\n\nOpenAI Ads answers 501: OpenAI documents only list and create for event settings, and\n`POST`/`PATCH`/`PUT /v1/conversions/event_settings/{id}` answer 404 \"Invalid URL\".\nCreate a new event instead.\n\nLinkedIn (`linkedinads`): partial update of the conversion rule; same fields as create.\nPass `adAccountId` when the rule lives in another ad account than the one that created the\ntag.\n\nMeta: only `name` and `defaultValue` can change (Meta's custom conversion update takes\nnothing else); `type`, `siteEvent` and `urlContains` answer 400, create a new event instead.\n\nGoogle Ads (`googleads`): same fields as create, on the account's WEBPAGE actions (others\nanswer 404). `enabled: false` archives the action (same as DELETE) and `enabled: true`\nrestores an archived one.\n\nPinterest (platform `pinterestads`): remaps the event to another `type` or `siteEvent`.\nPinterest identifies the event by its name, so `name` cannot change (400): create the new\nname and delete the old one.\n\nTikTok: `name`, `defaultValue` and `currency` (USD, JPY or INR); the type cannot change\n(delete and recreate).\n\nX Ads (platform `xads`): the same fields as create. Events X auto-created with the pixel\ncannot be changed (400).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"tagId","in":"path","required":true,"schema":{"type":"string"}},{"name":"eventId","in":"path","required":true,"schema":{"type":"string"},"description":"Event id (`TrackingTagEvent.id`)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackingTagEventInput"}}}},"responses":{"200":{"description":"Conversion event updated","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string"},"event":{"$ref":"#/components/schemas/TrackingTagEvent"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access, a permission or the account selection is missing: enable access, grant it, or add the ad account to the selection.","description":"Ads access required, or the platform token lacks the permission (reconnect required).\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the ad account this request targets is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nTo fix it, add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"The platform cannot update conversion events through its API (code `platform_not_supported`)."}}},"delete":{"x-resource-group":"ads","operationId":"deleteTrackingTagEvent","tags":["Tracking Tags"],"x-platforms":["meta","google","tiktok","linkedin","x","openai","pinterest"],"summary":"Delete a conversion event","description":"Removes a conversion event from a tracking tag, or archives or disables it on platforms that have no hard delete.\n\nPlatforms without a hard delete archive or disable it\ninstead; `state` in the response says which (`deleted`, `archived`, `disabled`).\n\nOpenAI Ads answers 501: there is no delete or archive route for event settings\n(`DELETE /v1/conversions/event_settings/{id}` and `POST .../{id}/archive` answer 404\n\"Invalid URL\"). Archive the event in OpenAI Ads Manager.\n\nLinkedIn (`linkedinads`): LinkedIn has no delete for conversion rules (not in the\nconversion-tracking API, and `DELETE /rest/conversions/{id}` has no route), so the rule is\ndisabled (`enabled: false`) and `state` is `disabled`. Re-enable it with `enabled: true`.\n\nMeta: `archived`. Meta's delete archives the custom conversion (it stays readable with\n`status: archived`) and there is no hard delete; deleting an archived one is a no-op.\n\nGoogle Ads (`googleads`): removes the conversion action (state `archived`). Google keeps\nit with status REMOVED and its history; PATCH with `enabled: true` restores it. Deleting\nan already archived action succeeds without a call to Google.\n\nPinterest (platform `pinterestads`): stops Pinterest tracking the event name (`state:\ndisabled`); Pinterest keeps the event's history.\n\nTikTok Ads answers 501: TikTok's `/pixel/event/delete/` answers OK but leaves the event on\nthe pixel, so nothing is deleted. Delete the event in TikTok Events Manager.\n\nX Ads (platform `xads`): deletes the web event tag for good. Events X auto-created with\nthe pixel cannot be deleted (400). X keeps the event's own website tag id on the account\n(it has no delete for website tags), left without a conversion event.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"tagId","in":"path","required":true,"schema":{"type":"string"}},{"name":"eventId","in":"path","required":true,"schema":{"type":"string"},"description":"Event id (`TrackingTagEvent.id`)."},{"name":"adAccountId","in":"query","required":false,"schema":{"type":"string"},"description":"Scopes the lookup on platforms whose tag ids live inside an ad account."}],"responses":{"200":{"description":"Conversion event removed","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string"},"eventId":{"type":"string"},"state":{"type":"string","enum":["deleted","archived","disabled"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access, a permission or the account selection is missing: enable access, grant it, or add the ad account to the selection.","description":"Ads access required, or the platform token lacks the permission (reconnect required).\n\nAlso returned with code `ad_account_not_selected` when the connection has selected ad accounts and the targeted ad account is not among them. `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`.\n\nFix: add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"The platform cannot remove conversion events through its API (code `platform_not_supported`)."}}}},"/v1/accounts/{accountId}/tracking-tags/{tagId}/users":{"get":{"x-resource-group":"ads","operationId":"listTrackingTagUsers","tags":["Tracking Tags"],"x-platforms":["meta"],"summary":"List tag users","description":"Lists the people and system users in the owning Meta business who have access to a pixel.\n\nPlatforms without\ntag user assignment answer 501.\n\nMeta: the pixel's assigned users in its owning Business Manager. A pixel on a personal ad\naccount has no business and returns an empty list. Needs the `business_management`\npermission on the connecting Meta user (an admin of the owning business); without it the\ncall answers 403 asking to reconnect.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"tagId","in":"path","required":true,"schema":{"type":"string"},"description":"Tag id (`TrackingTag.id`)."}],"responses":{"200":{"description":"Tag users listed","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string"},"users":{"type":"array","items":{"$ref":"#/components/schemas/TrackingTagUser"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads access required, or the platform token lacks the permission (reconnect required)."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"The platform has no tag user assignment (code `platform_not_supported`)."}}},"post":{"x-resource-group":"ads","operationId":"assignTrackingTagUser","tags":["Tracking Tags"],"x-platforms":["meta"],"summary":"Assign a user to a tag","description":"Gives a person in the owning Meta business access to a pixel, or replaces the tasks they already have on it.\n\nAssigning an already assigned user\nreplaces their task set.\n\nMeta: `tasks` are `AA_ANALYZE`, `ADVERTISE`, `ANALYZE`, `EDIT`, `UPLOAD`; `userId` is the\nbusiness-scoped id from `GET /v1/ads/businesses/users`. A pixel on a personal ad account\nanswers 400. Needs `business_management` like the list.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"tagId","in":"path","required":true,"schema":{"type":"string"},"description":"Tag id (`TrackingTag.id`)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userId","tasks"],"additionalProperties":false,"properties":{"userId":{"type":"string","pattern":"^[1-9][0-9]{0,24}$"},"tasks":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"User assigned","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string"},"userId":{"type":"string"},"tasks":{"type":"array","items":{"type":"string"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads access required, or the platform token lacks the permission (reconnect required)."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"The platform has no tag user assignment (code `platform_not_supported`)."}}}},"/v1/accounts/{accountId}/tracking-tags/{tagId}/users/{userId}":{"delete":{"x-resource-group":"ads","operationId":"removeTrackingTagUser","tags":["Tracking Tags"],"x-platforms":[],"summary":"Remove a user from a tag","description":"Removes a user's access to the tag, on platforms whose API allows it.\n\nMeta answers 501: the Business SDK has no delete on the pixel's assigned users, `DELETE\n/{pixel}/assigned_users` answers \"Unsupported delete request\" (code 100, subcode 33) and\nre-assigning with no tasks is refused. Remove the user in Business Settings.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"tagId","in":"path","required":true,"schema":{"type":"string"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"User id (`TrackingTagUser.id`)."}],"responses":{"200":{"description":"User removed","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string"},"userId":{"type":"string"},"removed":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads access required, or the platform token lacks the permission (reconnect required)."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"The platform cannot remove tag users through its API (code `platform_not_supported`); the message says where to do it."}}}},"/v1/accounts/{accountId}/tracking-tags/{tagId}/partners":{"get":{"x-resource-group":"ads","operationId":"listTrackingTagPartners","tags":["Tracking Tags"],"x-platforms":["meta"],"summary":"List partner businesses of a tag","description":"Lists the partner businesses a Meta pixel is shared with (read-only, sharing with new partners is not supported).\n\nRead-only. Platforms without partner sharing\nanswer 501.\n\nMeta: the pixel's shared agencies. Sharing a pixel with a new partner is not available:\n`/{pixel}/agencies` answers \"(#3) Application does not have the capability to make this\nAPI call\" for our app.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"tagId","in":"path","required":true,"schema":{"type":"string"},"description":"Tag id (`TrackingTag.id`)."}],"responses":{"200":{"description":"Partners listed","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string"},"partners":{"type":"array","items":{"$ref":"#/components/schemas/TrackingTagPartner"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads access required, or the platform token lacks the permission (reconnect required)."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"The platform has no partner sharing (code `platform_not_supported`)."}}}},"/v1/accounts/{accountId}/tracking-tags/{tagId}/diagnostics":{"get":{"x-resource-group":"ads","operationId":"getTrackingTagDiagnostics","tags":["Tracking Tags"],"x-platforms":["meta"],"summary":"Get tag diagnostics","description":"Shows Meta's health checks for a pixel, such as events missing parameters or product ids that do not match your catalogs.\n\nPlatforms without tag diagnostics answer 501.\n\nMeta: the pixel's checks from Events Manager (`da_checks`), e.g. whether events miss\nparameters or their content ids do not match the pixel's catalogs.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"tagId","in":"path","required":true,"schema":{"type":"string"},"description":"Tag id (`TrackingTag.id`)."}],"responses":{"200":{"description":"Diagnostics fetched","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string"},"checks":{"type":"array","items":{"$ref":"#/components/schemas/TrackingTagDiagnostic"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads access required, or the platform token lacks the permission (reconnect required)."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"501":{"description":"The platform has no tag diagnostics (code `platform_not_supported`)."},"502":{"x-summary":"The platform was unreachable or returned an unclassified error: retry later.","description":"The platform was unreachable or returned an unclassified error (type: platform_error). Retryable."}}}},"/v1/accounts/{accountId}/tracking-tags/{tagId}/stats":{"get":{"x-resource-group":"ads","operationId":"getTrackingTagStats","tags":["Tracking Tags"],"x-platforms":["meta","tiktok","google","x","openai","linkedin","pinterest"],"summary":"Get aggregated event stats","description":"Shows event counts or health for a tracking tag so you can confirm it is firing, where the platform reports them.\n\nPlatforms without a stats API answer 501.\n\n### Meta\n\nAggregated counts (`GET /{pixel_id}/stats`), rows passed through as-is. Their shape depends on the `aggregation` requested.\n\n### OpenAI Ads\n\nThe recent-events stream (`GET /conversions/events`): the latest (at most 50) events received in the last 15 minutes, one row per event (`event_type`, `api_channel`, `event_timestamp_ms`, `received_at_ms`, ...).\n\nBoth sources appear in `api_channel`:\n\n- `pixel_sdk`: the on-site Pixel (including its `openai::sdk_init` load event)\n- `server_to_server`: Conversions API events\n\nIt is a fixed window: `startTime`/`endTime` answer 400. Use it to confirm an install fires; attributed totals come from ads analytics.\n\nAccounts not enabled for the stream answer 422 `feature_not_available`.\n\n### LinkedIn (`linkedinads`)\n\nHealth rows rather than counts, since LinkedIn exposes no per-event fire counts:\n\n- One row per site domain the tag has seen (`kind: domain`, `domainName`, `lastFiredTime`, `creationTime`, `blocked`). Capped at the 100 domains that fired most recently (newest first; a tag seen on more domains drops the least recent).\n- One row per conversion rule (`kind: conversion_rule`, `id`, `name`, `type`, `conversionMethod`, `status`, `lastFiredTime`).\n\nTimes are unix seconds. `startTime`/`endTime` are ignored.\n\n### Pinterest (platform `pinterestads`)\n\nRows typed by `type`:\n\n- One `tag` row (`lastFiredTime`, `status`, `enhancedMatchStatus`).\n- `event` rows for the conversion events Pinterest has seen on the tag. `source` is `page_visit` or `ocpm_eligible` (the latter means the event can be optimized for), with the neutral `siteEvent` where one maps.\n- `event_quality` rows with the ad account's Event Quality Score for tag events over the last `1d` and `14d`. This is ad-account level, not per tag; an account Pinterest cannot score yet carries `error` instead.\n\nPinterest has no time-bounded counts, so `startTime`/`endTime` answer 400.\n\n### TikTok\n\nPer-event counts from `/pixel/event/stats/` (`total_count`, `browser_event_total_count`, `server_event_total_count`, `attributed_count`, `preview_count`), bucketed by UTC day.\n\nDefaults to the last 7 days; at most 30 days per request. `aggregation` is not accepted.\n\n### X Ads (platform `xads`)\n\nX has no event counts per pixel or event (only campaign-level conversion metrics). Each row is one web event tag with:\n\n- its `status` (TRACKING, UNVERIFIED, DORMANT)\n- `lastTrackedTime` (unix seconds, null if never seen)\n- `autoCreated`\n- for events the site can fire, `siteEventId`\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}},{"name":"tagId","in":"path","required":true,"schema":{"type":"string"},"description":"Tag id (`TrackingTag.id`)."},{"name":"adAccountId","in":"query","required":false,"schema":{"type":"string"},"description":"Scopes the lookup on platforms whose tag ids live inside an ad account. Ignored elsewhere."},{"name":"aggregation","in":"query","required":false,"schema":{"type":"string","default":"event","enum":["event","host","url","url_by_rule","pixel_fire","device_type","device_os","browser_type","had_pii","custom_data_field","match_keys","event_source","event_detection_method","event_processing_results","event_total_counts","event_value_count"]},"description":"Meta only (400 on other platforms): aggregation dimension. Defaults to `event`."},{"name":"startTime","in":"query","required":false,"schema":{"type":"integer"},"description":"Unix seconds lower bound."},{"name":"endTime","in":"query","required":false,"schema":{"type":"integer"},"description":"Unix seconds upper bound."}],"responses":{"200":{"description":"Stats fetched","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["metaads","tiktokads","googleads","xads","openaiads","linkedinads","pinterestads","whopads"]},"stats":{"type":"object","properties":{"aggregation":{"type":"string"},"startTime":{"type":"integer"},"endTime":{"type":"integer"},"rows":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}}},"400":{"x-summary":"A query parameter is invalid or the Meta time window is too large: fix the parameter or narrow the window.","description":"Invalid query parameter, or (Meta) the startTime/endTime window is too large for Meta to answer: narrow it, e.g. into 7-day ranges."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the Meta token lacks ads permissions: enable Ads access or reconnect the account.","description":"Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required)."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"The platform does not offer this operation (code `platform_not_supported`); the message names the reason and the alternative."},"502":{"x-summary":"Meta was unreachable or returned an unclassified error: retry the request.","description":"Meta was unreachable or returned an unclassified error (type: platform_error; the raw Meta payload is in platformError). Retryable."}}}},"/v1/accounts/{accountId}/blogs":{"get":{"x-resource-group":"publishing","operationId":"listBlogs","tags":["Blogs"],"x-platforms":["shopify","wordpress","wix","webflow"],"summary":"List blogs","description":"Lists blogs on the connected account. Supported on Shopify (`shopify`), WordPress (`wordpress`), Wix (`wix`) and Webflow (`webflow`).\n\n### By platform\n\n- Shopify: returns its store blogs with cursor pagination.\n- WordPress or Wix: the account represents one site and always returns exactly that one blog with `nextCursor: null`.\n- Webflow: returns each CMS collection that has a rich text field (its blog id is the collection id), with `nextCursor: null`.\n\n### Pagination\n\n`limit` is 1-50 (default 20). Treat `nextCursor` as opaque; pass it unchanged on the next request.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Connected Shopify, WordPress, Wix or Webflow account id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Page size (1-50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from a previous response. Omit for the first page."}],"responses":{"200":{"description":"Blogs listed","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["shopify","wordpress","wix","webflow"]},"blogs":{"type":"array","items":{"$ref":"#/components/schemas/Blog"}},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page; null when there are no more pages."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The platform rejected the request (code insufficient_permissions); reconnect the account or restore the WordPress user capabilities."},"404":{"description":"Account not found or not accessible (code account_not_found)."},"405":{"description":"Platform does not support listing blogs."},"429":{"x-summary":"Zernio or the connected platform rate limited the request: retry later.","description":"Rate limited by Zernio or the connected platform. Retry later."},"502":{"description":"The connected platform returned an unclassified upstream error."}}},"post":{"x-resource-group":"publishing","operationId":"createBlog","tags":["Blogs"],"x-platforms":["shopify"],"summary":"Create a blog","description":"Creates a blog on the connected store. The platform generates the URL\n`handle` from the title when omitted.\n\nSupported on Shopify (platform `shopify`). A WordPress or Wix\nconnection is its existing site, so both return 405 for blog creation.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Connected Shopify SocialAccount id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","minLength":1},"handle":{"type":"string","minLength":1,"description":"URL slug. Generated from the title when omitted."}}}}}},"responses":{"201":{"description":"Blog created","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["shopify"]},"blog":{"$ref":"#/components/schemas/Blog"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The platform rejected the request (code insufficient_permissions); reconnect the Shopify account to restore access."},"404":{"description":"Account not found or not accessible (code account_not_found)."},"405":{"description":"Platform does not support creating blogs."},"429":{"x-summary":"Zernio or Shopify rate limited the request: retry later.","description":"Rate limited, either by Zernio or by Shopify. Retry later."}}}},"/v1/accounts/{accountId}/blogs/{blogId}":{"get":{"x-resource-group":"publishing","operationId":"getBlog","tags":["Blogs"],"x-platforms":["shopify","wordpress","wix","webflow"],"summary":"Get a blog","description":"Fetches a single blog. Use the platform-native `blogId` returned by\n`GET /v1/accounts/{accountId}/blogs`: a Shopify numeric blog id, the\nWordPress.com numeric site id, or `1` for a self-hosted WordPress or a\nWix site. That `1` is scoped to its connected account.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Connected Shopify, WordPress, Wix or Webflow account id."},{"name":"blogId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"description":"Platform-native blog/site id returned by the list operation."}],"responses":{"200":{"description":"Blog fetched","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["shopify","wordpress","wix","webflow"]},"blog":{"$ref":"#/components/schemas/Blog"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The platform rejected the request (code insufficient_permissions); reconnect the account or restore the WordPress user capabilities."},"404":{"description":"Account not found or not accessible (code account_not_found), or blog not found (code blog_not_found)."},"405":{"description":"Platform does not support fetching a blog."},"429":{"x-summary":"Zernio or the connected platform rate limited the request: retry later.","description":"Rate limited by Zernio or the connected platform. Retry later."},"502":{"description":"The connected platform returned an unclassified upstream error."}}},"patch":{"x-resource-group":"publishing","operationId":"updateBlog","tags":["Blogs"],"x-platforms":["shopify"],"summary":"Update a blog","description":"Partial-updates a blog. Send any subset of `title` and `handle`; at\nleast one field is required (an empty body returns 400).\n\nSupported on Shopify (platform `shopify`). WordPress and Wix site\nsettings are not writable through this API, so both return 405.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Connected Shopify SocialAccount id."},{"name":"blogId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"description":"Platform-native blog id. Shopify blog ids are numeric; other values return 400."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"At least one field is required.","properties":{"title":{"type":"string","minLength":1},"handle":{"type":"string","minLength":1,"description":"URL slug. Changing it changes the blog URL on the store."}}}}}},"responses":{"200":{"description":"Blog updated","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["shopify"]},"blog":{"$ref":"#/components/schemas/Blog"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The platform rejected the request (code insufficient_permissions); reconnect the Shopify account to restore access."},"404":{"description":"Account not found or not accessible (code account_not_found), or blog not found (code blog_not_found)."},"405":{"description":"Platform does not support updating a blog."},"429":{"x-summary":"Zernio or Shopify rate limited the request: retry later.","description":"Rate limited, either by Zernio or by Shopify. Retry later."}}},"delete":{"x-resource-group":"publishing","operationId":"deleteBlog","tags":["Blogs"],"x-platforms":["shopify"],"summary":"Delete a blog","description":"Deletes the blog AND every article in it. The delete happens on the\nplatform and is permanent; Zernio stores nothing to restore it from.\n\nSupported on Shopify (platform `shopify`). Disconnect a WordPress or\nWix account instead of deleting its site; both return 405 here.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Connected Shopify SocialAccount id."},{"name":"blogId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"description":"Platform-native blog id. Shopify blog ids are numeric; other values return 400."}],"responses":{"204":{"description":"Blog deleted (no content)."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The platform rejected the request (code insufficient_permissions); reconnect the Shopify account to restore access."},"404":{"description":"Account not found or not accessible (code account_not_found), or blog not found (code blog_not_found)."},"405":{"description":"Platform does not support deleting a blog."},"429":{"x-summary":"Zernio or Shopify rate limited the request: retry later.","description":"Rate limited, either by Zernio or by Shopify. Retry later."}}}},"/v1/accounts/{accountId}/blogs/{blogId}/articles":{"get":{"x-resource-group":"publishing","operationId":"listBlogArticles","tags":["Blogs"],"x-platforms":["shopify","wordpress","wix","webflow"],"summary":"List blog articles","description":"Lists the articles of a blog. Supported on Shopify (`shopify`), WordPress (`wordpress`), Wix (`wix`) and Webflow (`webflow`).\n\n### Pagination\n\nCursor-paginated: pass `limit` (1-50, default 20) and the `cursor` from a previous response's `nextCursor`. `nextCursor` is null when there are no more pages. Treat cursors as opaque and pass them unchanged.\n\n### Platform differences\n\n- WordPress and Wix results include `status`, and include `publishDate` only for scheduled (`future`) posts.\n- Wix lists return `bodyHtml: null`; get the article for its body.\n- Webflow results report `status` as `publish` or `draft` only.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Connected Shopify, WordPress, Wix or Webflow account id."},{"name":"blogId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"description":"Platform-native blog/site id returned by the list operation."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Page size (1-50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from a previous response. Omit for the first page."}],"responses":{"200":{"description":"Articles listed","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["shopify","wordpress","wix","webflow"]},"articles":{"type":"array","items":{"$ref":"#/components/schemas/BlogArticle"}},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page; null when there are no more pages."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The platform rejected the request (code insufficient_permissions); reconnect the account or restore the WordPress user capabilities."},"404":{"description":"Account not found or not accessible (code account_not_found), or blog not found (code blog_not_found)."},"405":{"description":"Platform does not support listing articles."},"429":{"x-summary":"Zernio or the connected platform rate limited the request: retry later.","description":"Rate limited by Zernio or the connected platform. Retry later."},"502":{"description":"The connected platform returned an unclassified upstream error."}}},"post":{"x-resource-group":"publishing","operationId":"createBlogArticle","tags":["Blogs"],"x-platforms":["shopify","wordpress","wix","webflow"],"summary":"Create a blog article","description":"Creates an article on the blog. Supported on Shopify (`shopify`), WordPress (`wordpress`), Wix (`wix`) and Webflow (`webflow`).\n\n### Publishing behavior\n\n- WordPress, Wix and Webflow default to a draft when both publishing fields are omitted.\n- `isPublished: false` keeps the article as a draft and takes priority over a future `publishDate`.\n- A future `publishDate` schedules publication natively on the platform. The platform publishes it at that time with no Zernio queue involved.\n- `isPublished: true` publishes immediately when there is no future `publishDate`.\n- WordPress native scheduling depends on the site's scheduler/WP-Cron.\n\n### SEO\n\n`seo.title` / `seo.description` map to:\n\n- Shopify: the global `title_tag` and `description_tag` metafields (the fields Shopify themes read for the page title and meta description).\n- Wix: the post's SEO title and meta description.\n\nWordPress and Webflow reject `seo`; SEO plugin and custom-field writes are not supported.\n\n### Webflow\n\nWebflow has no scheduling API: a future `publishDate` returns 400 unless `isPublished: false` keeps a draft.\n\nFields map to the collection's own fields by type and slug:\n\n- The body goes to its rich text field.\n- `excerpt` goes to a summary field.\n- `image` goes to an image field.\n- `tags` and `author` go to tag and author reference fields.\n\nSending a field the collection does not have returns 400, as does a collection that requires a field the Blogs API cannot fill.\n\n### Wix\n\nWix stores rich content. `bodyHtml` is converted on write (each top-level HTML element must fit 30,000 characters), and images in the body are imported into the site's Media Manager.\n\n### Idempotency\n\nSend an Idempotency-Key header to make retries safe. A retry with the same key and body replays the original 201 instead of creating a second article. A retry while the first request is still running returns 409; retry after a short backoff.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Connected Shopify, WordPress, Wix or Webflow account id."},{"name":"blogId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"description":"Platform-native blog/site id returned by the list operation."},{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","minLength":1},"bodyHtml":{"type":"string","description":"Article body as HTML."},"handle":{"type":"string","description":"URL slug. Generated from the title when omitted."},"tags":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1},"description":"Tag names. WordPress and Wix resolve existing names case-insensitively and create missing tags (Wix allows up to 30)."},"author":{"type":"string","description":"Shopify author display name, numeric WordPress user id serialized as a string, or Wix site member id. Assigning another WordPress user may require elevated capability. Wix posts without one go to the site's default author."},"excerpt":{"type":"string","description":"Short summary shown in blog listings."},"image":{"type":"object","required":["url"],"description":"Featured image from a public URL. WordPress downloads it into the media library and Wix imports it into the Media Manager; JPEG, PNG, GIF and WebP are accepted up to 10 MB.","properties":{"url":{"type":"string","format":"uri"},"altText":{"type":"string"}}},"seo":{"type":"object","description":"Shopify and Wix. Search-engine overrides: Shopify global title_tag and description_tag metafields, Wix post SEO title and meta description. WordPress rejects this field.","properties":{"title":{"type":"string"},"description":{"type":"string"}}},"isPublished":{"type":"boolean","description":"Set false for a draft or true to publish. On WordPress and Wix false takes priority over a future publishDate; omission with no date defaults to draft."},"publishDate":{"type":"string","format":"date-time","description":"ISO 8601 datetime with offset (or Z). A future date schedules publication natively on the platform."},"fieldData":{"type":"object","additionalProperties":true,"description":"Webflow only (other platforms answer 400). The collection's own fields that the Blogs API does not map, keyed by field slug, in Webflow's value format (a Reference is an item id, an Image is { url, alt }).\n\nRequired by collections with required fields of their own: a create that leaves one empty answers 400 listing them. A slug the API already fills (name, slug, body, summary, image, tags, author, date) or one the collection lacks answers 400."}}}}}},"responses":{"201":{"description":"Article created","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["shopify","wordpress","wix","webflow"]},"article":{"$ref":"#/components/schemas/BlogArticle"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The platform rejected the request (code insufficient_permissions); reconnect the account or restore the WordPress user capabilities."},"404":{"description":"Account not found or not accessible (code account_not_found), or blog not found (code blog_not_found)."},"405":{"description":"Platform does not support creating articles."},"409":{"$ref":"#/components/responses/IdempotencyKeyInFlight"},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"},"429":{"x-summary":"Zernio or the connected platform rate limited the request: retry later.","description":"Rate limited by Zernio or the connected platform. Retry later."},"502":{"x-summary":"The connected platform returned an unclassified upstream error: check the article state before repeating the request.","description":"The connected platform returned an unclassified upstream error. Article mutations are not blindly retried."}}}},"/v1/accounts/{accountId}/blogs/{blogId}/articles/{articleId}":{"get":{"x-resource-group":"publishing","operationId":"getBlogArticle","tags":["Blogs"],"x-platforms":["shopify","wordpress","wix","webflow"],"summary":"Get a blog article","description":"Fetches a single article. An article addressed through a blog it does\nnot belong to is a 404 (code blog_article_not_found).\n\nSupported on Shopify (`shopify`), WordPress (`wordpress`), Wix (`wix`) and Webflow (`webflow`). WordPress\nreturns its native `status`; `publishedAt` is present only for a\npublished post and `publishDate` only for a scheduled post.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Connected Shopify, WordPress, Wix or Webflow account id."},{"name":"blogId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"description":"Platform-native blog/site id returned by the list operation."},{"name":"articleId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"description":"Platform-native article id: numeric on Shopify and WordPress, a GUID on Wix, a 24-character hex item id on Webflow. Other formats return 400."}],"responses":{"200":{"description":"Article fetched","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["shopify","wordpress","wix","webflow"]},"article":{"$ref":"#/components/schemas/BlogArticle"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The platform rejected the request (code insufficient_permissions); reconnect the account or restore the WordPress user capabilities."},"404":{"x-summary":"The account, blog or article was not found: check the IDs in the path.","description":"Account not found or not accessible (code account_not_found), blog not found (code blog_not_found), or article not found (code blog_article_not_found)."},"405":{"description":"Platform does not support fetching an article."},"429":{"x-summary":"Zernio or the connected platform rate limited the request: retry later.","description":"Rate limited by Zernio or the connected platform. Retry later."},"502":{"description":"The connected platform returned an unclassified upstream error."}}},"patch":{"x-resource-group":"publishing","operationId":"updateBlogArticle","tags":["Blogs"],"x-platforms":["shopify","wordpress","wix","webflow"],"summary":"Update a blog article","description":"Partial-updates an article. Supported on Shopify (`shopify`), WordPress (`wordpress`), Wix (`wix`) and Webflow (`webflow`).\n\nSend any subset of the create fields: `title`, `bodyHtml`, `handle`, `tags`, `author`, `excerpt`, `image`, `seo`, `isPublished`, `publishDate`. At least one field is required (an empty body returns 400).\n\n### Publishing\n\n`isPublished` and `publishDate` behave as on create:\n\n- `isPublished: false` unpublishes back to a draft.\n- A future `publishDate` schedules publication natively on the platform.\n- Omitting both fields preserves the current WordPress or Wix status.\n\nOmitting `image` preserves the current featured image; removal is not supported.\n\n### Platform limits\n\n- **WordPress**: rejects `seo` and does not support SEO-plugin/custom-field, category, or custom-post-type writes.\n- **Webflow**: an edit to a published item goes live immediately, `isPublished: false` unpublishes it, and a future `publishDate` returns 400.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Connected Shopify, WordPress, Wix or Webflow account id."},{"name":"blogId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"description":"Platform-native blog/site id returned by the list operation."},{"name":"articleId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"description":"Platform-native article id: numeric on Shopify and WordPress, a GUID on Wix, a 24-character hex item id on Webflow. Other formats return 400."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"At least one field is required.","properties":{"title":{"type":"string","minLength":1},"bodyHtml":{"type":"string","description":"Article body as HTML."},"handle":{"type":"string","description":"URL slug of the article."},"tags":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1},"description":"Replaces the full tag-name list. WordPress and Wix resolve existing names case-insensitively and create missing tags (Wix allows up to 30)."},"author":{"type":"string","description":"Shopify author display name, numeric WordPress user id serialized as a string, or Wix site member id. Assigning another WordPress user may require elevated capability. Wix posts without one go to the site's default author."},"excerpt":{"type":"string","description":"Short summary shown in blog listings."},"image":{"type":"object","required":["url"],"description":"Featured image from a public URL. WordPress downloads it into the media library and Wix imports it into the Media Manager; JPEG, PNG, GIF and WebP are accepted up to 10 MB. Omit to preserve it; null removal is not supported.","properties":{"url":{"type":"string","format":"uri"},"altText":{"type":"string"}}},"seo":{"type":"object","description":"Shopify and Wix. Search-engine overrides: Shopify global title_tag and description_tag metafields, Wix post SEO title and meta description. WordPress rejects this field.","properties":{"title":{"type":"string"},"description":{"type":"string"}}},"isPublished":{"type":"boolean","description":"Set false to move to draft or true to publish. On WordPress and Wix false takes priority over a future publishDate; omission preserves status unless publishDate is sent (edits to a published Wix post go live)."},"publishDate":{"type":"string","format":"date-time","description":"ISO 8601 datetime with offset (or Z). A future date schedules publication natively on the platform."},"fieldData":{"type":"object","additionalProperties":true,"description":"Webflow only (other platforms answer 400). The collection's own fields that the Blogs API does not map, keyed by field slug, in Webflow's value format (a Reference is an item id, an Image is { url, alt }).\n\n- Required by collections with required fields of their own. A create that leaves one empty answers 400 listing them.\n- A slug the API already fills (name, slug, body, summary, image, tags, author, date) or one the collection lacks answers 400."}}}}}},"responses":{"200":{"description":"Article updated","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["shopify","wordpress","wix","webflow"]},"article":{"$ref":"#/components/schemas/BlogArticle"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The platform rejected the request (code insufficient_permissions); reconnect the account or restore the WordPress user capabilities."},"404":{"x-summary":"The account, blog or article was not found: check the IDs in the path.","description":"Account not found or not accessible (code account_not_found), blog not found (code blog_not_found), or article not found (code blog_article_not_found)."},"405":{"description":"Platform does not support updating an article."},"429":{"x-summary":"Zernio or the connected platform rate limited the request: retry later.","description":"Rate limited by Zernio or the connected platform. Retry later."},"502":{"x-summary":"The connected platform returned an unclassified upstream error: check the article state before repeating the request.","description":"The connected platform returned an unclassified upstream error. Article mutations are not blindly retried."}}},"delete":{"x-resource-group":"publishing","operationId":"deleteBlogArticle","tags":["Blogs"],"x-platforms":["shopify","wordpress","wix","webflow"],"summary":"Delete a blog article","description":"Deletes the article. The delete happens on the platform and is permanent; Zernio stores nothing to restore it from.\n\nSupported on Shopify (`shopify`), WordPress (`wordpress`), Wix (`wix`) and Webflow (`webflow`).\n\n### Platform behavior\n\n- WordPress: the post is force-deleted, while uploaded attachments and tags remain in the site's media library and taxonomy.\n- Webflow: the item is unpublished from the live site, then deleted from the collection.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Connected Shopify, WordPress, Wix or Webflow account id."},{"name":"blogId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"description":"Platform-native blog/site id returned by the list operation."},{"name":"articleId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"description":"Platform-native article id: numeric on Shopify and WordPress, a GUID on Wix, a 24-character hex item id on Webflow. Other formats return 400."}],"responses":{"204":{"description":"Article deleted (no content)."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The platform rejected the request (code insufficient_permissions); reconnect the account or restore the WordPress user capabilities."},"404":{"x-summary":"The account, blog or article was not found: check the IDs in the path.","description":"Account not found or not accessible (code account_not_found), blog not found (code blog_not_found), or article not found (code blog_article_not_found)."},"405":{"description":"Platform does not support deleting an article."},"429":{"x-summary":"Zernio or the connected platform rate limited the request: retry later.","description":"Rate limited by Zernio or the connected platform. Retry later."},"502":{"x-summary":"The connected platform returned an unclassified upstream error: check whether the article still exists before repeating the request.","description":"The connected platform returned an unclassified upstream error. Article deletion is not blindly retried."}}}},"/v1/accounts/{accountId}/products":{"get":{"x-resource-group":"commerce","operationId":"listProducts","deprecated":true,"tags":["Products"],"x-platforms":["shopify"],"summary":"List products","description":"Lists the products on the connected store in the platform's default order, each with its variants, options and images.\n\n### Paging and filters\n\n- Cursor-paginated: pass `limit` (1-50, default 20) and the `cursor` from a previous response's `nextCursor`. `nextCursor` is null when there are no more pages.\n- Filter with `status` and/or `query` (the platform's product search syntax, e.g. `title:*shirt* vendor:Acme tag:summer`).\n\n### Platforms\n\nSupported on Shopify (platform `shopify`); accounts on other platforms return 400.\n\nA store connected before product access was added answers 403 insufficient_permissions until the merchant reconnects it through `GET /v1/connect/shopify`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Connected Shopify SocialAccount id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Page size (1-50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from a previous response. Omit for the first page."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","draft","archived"]},"description":"Only products in this status."},{"name":"query","in":"query","required":false,"schema":{"type":"string","maxLength":500},"description":"Platform product search syntax, passed through verbatim (Shopify: title, vendor, product_type, tag, sku, handle, created_at, updated_at, ...)."}],"responses":{"200":{"description":"Products listed","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["shopify"]},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page; null when there are no more pages."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The store lacks the product permissions or the token was revoked: reconnect the Shopify account.","description":"The platform rejected the request (code insufficient_permissions). The store lacks the product scopes or the token was revoked; reconnect the Shopify account."},"404":{"description":"Account not found or not accessible (code account_not_found)."},"429":{"x-summary":"Zernio or Shopify rate limited the request: retry later.","description":"Rate limited, either by Zernio or by Shopify. Retry later."}}}},"/v1/accounts/{accountId}/products/{productId}":{"get":{"x-resource-group":"commerce","operationId":"getProduct","deprecated":true,"tags":["Products"],"x-platforms":["shopify"],"summary":"Get a product","description":"Fetches a single product with its variants, options and images.\n`productId` is the platform's numeric product id from\n`GET /v1/accounts/{accountId}/products`, not a Zernio id.\n\nSupported on Shopify (platform `shopify`); accounts on other\nplatforms return 400.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Connected Shopify SocialAccount id."},{"name":"productId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Platform-native numeric product id. Non-numeric values return 400."}],"responses":{"200":{"description":"Product fetched","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["shopify"]},"product":{"$ref":"#/components/schemas/Product"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The store lacks the product permissions or the token was revoked: reconnect the Shopify account.","description":"The platform rejected the request (code insufficient_permissions). The store lacks the product scopes or the token was revoked; reconnect the Shopify account."},"404":{"description":"Account not found or not accessible (code account_not_found), or product not found (code product_not_found)."},"429":{"x-summary":"Zernio or Shopify rate limited the request: retry later.","description":"Rate limited, either by Zernio or by Shopify. Retry later."}}},"patch":{"x-resource-group":"commerce","operationId":"updateProduct","deprecated":true,"tags":["Products"],"x-platforms":["shopify"],"summary":"Update a product","description":"Partial-updates a product. Responds with the product as it is after the update.\n\n### Fields\n\nSend any subset of these; at least one field is required (an empty body returns 400):\n\n- `title`\n- `descriptionHtml`\n- `handle`\n- `vendor`\n- `productType`\n- `tags`: replaces the full tag list\n- `status`\n- `seo`\n- `variants`: updates the price and compare-at price of the listed variant ids only. Other variants are untouched, and a variant id that does not belong to the product is a 400.\n\n### Platform support\n\nSupported on Shopify (platform `shopify`); accounts on other platforms return 400.\n\nA store connected before product access was added answers 403 insufficient_permissions until the merchant reconnects it through `GET /v1/connect/shopify`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"Connected Shopify SocialAccount id."},{"name":"productId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Platform-native numeric product id. Non-numeric values return 400."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"At least one field is required.","properties":{"title":{"type":"string","minLength":1},"descriptionHtml":{"type":"string","description":"Product description as HTML."},"handle":{"type":"string","minLength":1,"description":"URL slug of the product."},"vendor":{"type":"string"},"productType":{"type":"string"},"tags":{"type":"array","items":{"type":"string"},"description":"Replaces the full tag list."},"status":{"type":"string","enum":["active","draft","archived"],"description":"archived hides the product everywhere; draft keeps it editable but unpublished."},"seo":{"type":"object","description":"Search-engine title and description overrides.","properties":{"title":{"type":"string"},"description":{"type":"string"}}},"variants":{"type":"array","minItems":1,"maxItems":100,"description":"Price changes per variant. Only the listed variants change.","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","pattern":"^\\d+$","description":"Variant id from the product response."},"price":{"oneOf":[{"type":"number","minimum":0},{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$"}],"description":"Decimal amount in the store currency. Numbers are formatted to two decimals."},"compareAtPrice":{"oneOf":[{"type":"number","minimum":0},{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$"},{"type":"null"}],"description":"Strike-through price. Send null to remove it."}}}}}}}}},"responses":{"200":{"description":"Product updated","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["shopify"]},"product":{"$ref":"#/components/schemas/Product"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The store lacks the product permissions or the token was revoked: reconnect the Shopify account.","description":"The platform rejected the request (code insufficient_permissions). The store lacks the product scopes or the token was revoked; reconnect the Shopify account."},"404":{"description":"Account not found or not accessible (code account_not_found), or product not found (code product_not_found)."},"429":{"x-summary":"Zernio or Shopify rate limited the request: retry later.","description":"Rate limited, either by Zernio or by Shopify. Retry later."}}}},"/v1/commerce/store":{"get":{"x-resource-group":"commerce","operationId":"getCommerceStore","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Get a store","description":"Returns the connected store with its currency, country and the `capabilities` it supports, so an integration can tell up front which Commerce operations the store serves.\n\n### Shopify permissions\n\nOn Shopify, these need permissions the store owner approves separately: stock, sales channels, discounts, navigation, metaobjects, markets, marketing and image removal.\n\n- `missingCapabilities` lists what is not granted yet.\n- `grantPermissionsUrl` is the page where the owner approves it.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Store fetched","content":{"application/json":{"schema":{"type":"object","properties":{"store":{"$ref":"#/components/schemas/CommerceStore"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access, usually a revoked token or missing permission: reconnect the store.","description":"The platform rejected the request (code insufficient_permissions). Reconnect the store."},"404":{"description":"Account not found or not accessible (code account_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/orders":{"get":{"x-resource-group":"commerce","operationId":"listCommerceOrders","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"List orders","description":"The store's orders in one format for every platform, with what an invoice needs. Needs orders.read.\n\nEach order includes:\n\n- line items with unit prices, discounts and tax per line\n- shipping and fee lines\n- billing details\n- payment status and refunds\n\n### Ordering and syncing\n\nNewest order first. With `updatedAfter`, oldest change first, so a sync can page forward from its last seen `updatedAt`.\n\nStart each sync a few minutes before the last `updatedAt` you saw and drop duplicates by `id`, since an order edited while you page can shift the list.\n\n### Limits\n\n- Shopify returns at most 25 orders per page and, unless the store was granted access to all orders, only the last 60 days.\n- Buyer fields (`customer` and addresses) are null when the store's approval does not cover buyer data.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"createdAfter","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"createdBefore","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"updatedAfter","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only orders changed after this time, oldest change first."}],"responses":{"200":{"description":"Orders listed","content":{"application/json":{"schema":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/CommerceOrder"}},"nextCursor":{"type":["string","null"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The store has not granted order access: have the store owner approve it using `grantPermissionsUrl` from the store endpoint.","description":"The store has not granted orders.read, or the platform has not yet approved Zernio's access to order and customer data (code insufficient_permissions; the message says which). GET /v1/commerce/store returns grantPermissionsUrl for the store owner to approve orders.read."},"404":{"description":"Account not found (code account_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/orders/{orderId}":{"get":{"x-resource-group":"commerce","operationId":"getCommerceOrder","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Get an order","description":"One order with every line item, tax line and refund. Needs orders.read.","security":[{"bearerAuth":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native order id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"The order","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/CommerceOrder"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The store has not granted order access: have the store owner approve it using `grantPermissionsUrl` from the store endpoint.","description":"The store has not granted orders.read, or the platform has not yet approved Zernio's access to order and customer data (code insufficient_permissions; the message says which). GET /v1/commerce/store returns grantPermissionsUrl for the store owner to approve orders.read."},"404":{"description":"Account not found (code account_not_found) or order not found (code resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/products":{"get":{"x-resource-group":"commerce","operationId":"listCommerceProducts","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"List products","description":"Lists the store's products with their variants, options and images.\n\n- Cursor-paginated: pass `limit` (1-100, default 20) and the `cursor` from a previous response's `nextCursor`, which is null on the last page.\n- Filter with `status` and/or `query` (the platform's product search syntax, passed through verbatim).\n- A status the platform has no equivalent of returns an empty page.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from a previous response. Omit for the first page."},{"name":"status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/CommerceProductStatus"}},{"name":"query","in":"query","required":false,"schema":{"type":"string","maxLength":500},"description":"Platform product search syntax (Shopify: title, vendor, product_type, tag, sku, handle, ...)."},{"name":"collectionId","in":"query","required":false,"schema":{"type":"string"},"description":"Only products in this collection."}],"responses":{"200":{"description":"Products listed","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/CommerceProduct"}},"nextCursor":{"type":["string","null"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect a Shopify store connected before product access was added.","description":"The platform rejected the request (code insufficient_permissions). A Shopify store connected before product access was added must be reconnected through GET /v1/connect/shopify."},"404":{"description":"Account not found or not accessible (code account_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"post":{"x-resource-group":"commerce","operationId":"createCommerceProduct","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Create a product","description":"Creates a product with its options and variants.\n\n- `status` defaults to `draft`: no platform offers a sandbox for product writes, so nothing goes on sale unless you ask for `active`.\n- A product without `options` has exactly one variant.\n- Images are fetched by the platform from the given URLs and may appear on the product a few seconds later.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","title","variants"],"properties":{"accountId":{"type":"string"},"title":{"type":"string","minLength":1},"descriptionHtml":{"type":"string"},"handle":{"type":"string","minLength":1},"vendor":{"type":"string"},"productType":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"seo":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"}}},"status":{"type":"string","enum":["draft","active"],"default":"draft"},"images":{"type":"array","maxItems":20,"items":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"altText":{"type":"string"}}}},"options":{"type":"array","maxItems":3,"items":{"type":"object","required":["name","values"],"properties":{"name":{"type":"string","example":"Size"},"values":{"type":"array","minItems":1,"items":{"type":"string"},"example":["S","M","L"]}}}},"variants":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["price"],"properties":{"sku":{"type":"string"},"price":{"oneOf":[{"type":"number","minimum":0},{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$"}],"description":"Decimal amount in the store currency."},"compareAtPrice":{"oneOf":[{"type":"number","minimum":0},{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$"},{"type":"null"}]},"options":{"type":"array","description":"One value per product option, e.g. [{ name: Size, value: M }].","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}}}}}}}}}},"responses":{"201":{"description":"Product created","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/CommerceProduct"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access, usually a revoked token or missing permission: reconnect the store.","description":"The platform rejected the request (code insufficient_permissions). Reconnect the store."},"404":{"description":"Account not found or not accessible (code account_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/products/state":{"post":{"x-resource-group":"commerce","operationId":"changeCommerceProductState","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Activate, deactivate, archive or delete products","description":"Applies one action to up to 50 products and reports each product's\noutcome, so one failure does not abort the rest. On Shopify,\n`deactivate` sets the product to draft and `delete` is permanent.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","productIds","action"],"properties":{"accountId":{"type":"string"},"productIds":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"}},"action":{"type":"string","enum":["activate","deactivate","archive","delete"]}}}}}},"responses":{"200":{"description":"Action applied","content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["activate","deactivate","archive","delete"]},"succeeded":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string"},"message":{"type":"string"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found or not accessible (code account_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/products/{productId}":{"get":{"x-resource-group":"commerce","operationId":"getCommerceProduct","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Get a product","description":"One product with all its variants, options and images. Needs products.read. 404 product_not_found when the id does not exist in the store.","security":[{"bearerAuth":[]}],"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native product id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Product fetched","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/CommerceProduct"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found (code account_not_found) or product not found (code product_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"patch":{"x-resource-group":"commerce","operationId":"updateCommerceProduct","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Update a product","description":"Partial-updates the product's own fields; at least one besides\n`accountId` is required. `tags` replaces the full list. Change prices\nwith `POST /v1/commerce/products/{productId}/price` and status with\n`POST /v1/commerce/products/state`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native product id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string"},"title":{"type":"string","minLength":1},"descriptionHtml":{"type":"string"},"handle":{"type":"string","minLength":1},"vendor":{"type":"string"},"productType":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"seo":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Product updated","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/CommerceProduct"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found (code account_not_found) or product not found (code product_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/products/{productId}/price":{"post":{"x-resource-group":"commerce","operationId":"updateCommerceProductPrices","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Update variant prices","description":"Sets the price and/or compare-at price of the listed variants. Other\nvariants are untouched. Amounts are in the store currency; send\n`compareAtPrice: null` to remove a strike-through price.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native product id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","variants"],"properties":{"accountId":{"type":"string"},"variants":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["id"],"description":"Needs a price or a compareAtPrice.","properties":{"id":{"type":"string","description":"Variant id from the product response."},"price":{"oneOf":[{"type":"number","minimum":0},{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$"}]},"compareAtPrice":{"oneOf":[{"type":"number","minimum":0},{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$"},{"type":"null"}]}}}}}}}}},"responses":{"200":{"description":"Prices updated","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/CommerceProduct"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found (code account_not_found) or product not found (code product_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/collections":{"get":{"x-resource-group":"commerce","operationId":"listCommerceCollections","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"List collections","description":"Lists the store's product collections. Cursor-paginated like products.\nList a collection's products with `GET /v1/commerce/products?collectionId=...`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"query","in":"query","required":false,"schema":{"type":"string","maxLength":500},"description":"Platform collection search syntax (Shopify: title, handle, collection_type, ...)."}],"responses":{"200":{"description":"Collections listed","content":{"application/json":{"schema":{"type":"object","properties":{"collections":{"type":"array","items":{"$ref":"#/components/schemas/CommerceCollection"}},"nextCursor":{"type":["string","null"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access, usually a revoked token or missing permission: reconnect the store.","description":"The platform rejected the request (code insufficient_permissions). Reconnect the store."},"404":{"description":"Account not found (code account_not_found) or collection not found (code resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"post":{"x-resource-group":"commerce","operationId":"createCommerceCollection","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Create a collection","description":"Creates a collection, optionally with hand-picked products. On Shopify\nthe collection starts unpublished from the online store; publish it\nfrom the Shopify admin.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","title"],"properties":{"accountId":{"type":"string"},"title":{"type":"string","minLength":1},"descriptionHtml":{"type":"string"},"handle":{"type":"string","minLength":1},"sortOrder":{"type":"string","enum":["manual","best_selling","alpha_asc","alpha_desc","price_asc","price_desc","created","created_desc","most_relevant"]},"seo":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"}}},"image":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"altText":{"type":"string"}}},"productIds":{"type":"array","maxItems":250,"items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Collection created","content":{"application/json":{"schema":{"type":"object","properties":{"collection":{"$ref":"#/components/schemas/CommerceCollection"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access, usually a revoked token or missing permission: reconnect the store.","description":"The platform rejected the request (code insufficient_permissions). Reconnect the store."},"404":{"description":"Account not found (code account_not_found) or collection not found (code resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/collections/{collectionId}":{"get":{"x-resource-group":"commerce","operationId":"getCommerceCollection","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Get a collection","description":"One collection (a category on WooCommerce) with its image, sort order and product count. List its products with GET /v1/commerce/products?collectionId=. Needs collections.read.","security":[{"bearerAuth":[]}],"parameters":[{"name":"collectionId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native collection id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Collection fetched","content":{"application/json":{"schema":{"type":"object","properties":{"collection":{"$ref":"#/components/schemas/CommerceCollection"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access, usually a revoked token or missing permission: reconnect the store.","description":"The platform rejected the request (code insufficient_permissions). Reconnect the store."},"404":{"description":"Account not found (code account_not_found) or collection not found (code resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"patch":{"x-resource-group":"commerce","operationId":"updateCommerceCollection","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Update a collection","description":"Partial update; at least one field besides accountId is required. Change membership with POST /v1/commerce/collections/{collectionId}/products.","security":[{"bearerAuth":[]}],"parameters":[{"name":"collectionId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native collection id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string"},"title":{"type":"string","minLength":1},"descriptionHtml":{"type":"string"},"handle":{"type":"string","minLength":1},"sortOrder":{"type":"string","enum":["manual","best_selling","alpha_asc","alpha_desc","price_asc","price_desc","created","created_desc","most_relevant"]},"seo":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"}}},"image":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"altText":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Collection updated","content":{"application/json":{"schema":{"type":"object","properties":{"collection":{"$ref":"#/components/schemas/CommerceCollection"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access, usually a revoked token or missing permission: reconnect the store.","description":"The platform rejected the request (code insufficient_permissions). Reconnect the store."},"404":{"description":"Account not found (code account_not_found) or collection not found (code resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"delete":{"x-resource-group":"commerce","operationId":"deleteCommerceCollection","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Delete a collection","description":"Deletes the collection. Its products are not affected.","security":[{"bearerAuth":[]}],"parameters":[{"name":"collectionId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native collection id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Collection deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"collectionId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access, usually a revoked token or missing permission: reconnect the store.","description":"The platform rejected the request (code insufficient_permissions). Reconnect the store."},"404":{"description":"Account not found (code account_not_found) or collection not found (code resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/collections/{collectionId}/products":{"post":{"x-resource-group":"commerce","operationId":"changeCommerceCollectionProducts","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Add or remove products in a collection","description":"Adds and/or removes hand-picked products. Products a collection\nincludes through its own rules are not affected. `pending` is true\nwhen the platform finishes the change in the background; the product\ncount then catches up a few seconds later.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"collectionId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native collection id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"description":"At least one product id in add or remove.","properties":{"accountId":{"type":"string"},"add":{"type":"array","maxItems":250,"items":{"type":"string"}},"remove":{"type":"array","maxItems":250,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Membership changed","content":{"application/json":{"schema":{"type":"object","properties":{"collection":{"$ref":"#/components/schemas/CommerceCollection"},"pending":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access, usually a revoked token or missing permission: reconnect the store.","description":"The platform rejected the request (code insufficient_permissions). Reconnect the store."},"404":{"description":"Account not found (code account_not_found) or collection not found (code resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/products/{productId}/variants":{"post":{"x-resource-group":"commerce","operationId":"createCommerceProductVariants","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Add variants","description":"Adds variants to a product. Each variant names a value for every product option (create options first with POST .../options). A product's placeholder default variant is replaced when real ones arrive.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","variants"],"properties":{"accountId":{"type":"string"},"variants":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["price"],"properties":{"sku":{"type":"string"},"price":{"oneOf":[{"type":"number","minimum":0},{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$"}]},"compareAtPrice":{"oneOf":[{"type":"number","minimum":0},{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$"},{"type":"null"}]},"options":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}}}}}}}}}}}},"responses":{"200":{"description":"Product after the change","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/CommerceProduct"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"delete":{"x-resource-group":"commerce","operationId":"deleteCommerceProductVariants","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Delete variants","description":"Deletes the variants in `variantIds` (comma-separated, up to 100) and returns the updated product. A product keeps at least one variant, so deleting every variant is refused by the platform. Needs products.variants.","security":[{"bearerAuth":[]}],"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."},{"name":"variantIds","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated ids."}],"responses":{"200":{"description":"Product after the change","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/CommerceProduct"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/products/{productId}/options":{"post":{"x-resource-group":"commerce","operationId":"createCommerceProductOptions","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Add options","description":"Adds option axes (e.g. Size, Color) and their values. With createVariants true the platform creates a variant for every new combination; otherwise existing variants take the first value.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","options"],"properties":{"accountId":{"type":"string"},"options":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"object","required":["name","values"],"properties":{"name":{"type":"string"},"values":{"type":"array","minItems":1,"items":{"type":"string"}}}}},"createVariants":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Product after the change","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/CommerceProduct"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"delete":{"x-resource-group":"commerce","operationId":"deleteCommerceProductOptions","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Delete options","description":"Deletes options by name, with the variants that depended on them.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."},{"name":"names","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated option names."}],"responses":{"200":{"description":"Product after the change","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/CommerceProduct"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/products/{productId}/images":{"post":{"x-resource-group":"commerce","operationId":"addCommerceProductImages","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Add images","description":"Adds images from public URLs. The platform fetches them, so they can appear on the product a few seconds after the call returns.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","images"],"properties":{"accountId":{"type":"string"},"images":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"altText":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Product after the change","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/CommerceProduct"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"delete":{"x-resource-group":"commerce","operationId":"removeCommerceProductImages","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Remove images","description":"Removes images from the product by image id (the `id` on each image). The file stays in the store's media library. Needs the products.images_remove capability.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."},{"name":"imageIds","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated ids."}],"responses":{"200":{"description":"Product after the change","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/CommerceProduct"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/products/{productId}/images/reorder":{"post":{"x-resource-group":"commerce","operationId":"reorderCommerceProductImages","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Reorder images","description":"Puts the product's images in the given order; the first becomes the featured image. `pending` is true while the platform finishes in the background.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","imageIds"],"properties":{"accountId":{"type":"string"},"imageIds":{"type":"array","minItems":1,"maxItems":250,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Reorder accepted","content":{"application/json":{"schema":{"type":"object","properties":{"pending":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/products/{productId}/duplicate":{"post":{"x-resource-group":"commerce","operationId":"duplicateCommerceProduct","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Duplicate a product","description":"Copies a product with its options, variants and (by default) images. The copy starts as a draft.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","title"],"properties":{"accountId":{"type":"string"},"title":{"type":"string","minLength":1},"status":{"type":"string","enum":["draft","active"],"default":"draft"},"includeImages":{"type":"boolean","default":true}}}}}},"responses":{"201":{"description":"Product duplicated","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/CommerceProduct"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/products/{productId}/metafields":{"get":{"x-resource-group":"commerce","operationId":"listCommerceProductMetafields","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"List product metafields","description":"The product's custom fields (metafields on Shopify, public meta on WooCommerce) as namespace, key, type and value. Needs metafields.read.","security":[{"bearerAuth":[]}],"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Metafields listed","content":{"application/json":{"schema":{"type":"object","properties":{"metafields":{"type":"array","items":{"$ref":"#/components/schemas/CommerceMetafield"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"put":{"x-resource-group":"commerce","operationId":"setCommerceProductMetafields","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Set product metafields","description":"Creates or updates custom fields by namespace and key.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","metafields"],"properties":{"accountId":{"type":"string"},"metafields":{"type":"array","minItems":1,"maxItems":25,"items":{"$ref":"#/components/schemas/CommerceMetafield"}}}}}}},"responses":{"200":{"description":"Metafields set","content":{"application/json":{"schema":{"type":"object","properties":{"metafields":{"type":"array","items":{"$ref":"#/components/schemas/CommerceMetafield"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"delete":{"x-resource-group":"commerce","operationId":"deleteCommerceProductMetafields","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Delete product metafields","description":"Deletes the product custom fields named in `keys` (comma-separated `namespace.key`, up to 25) and returns how many were deleted. Needs metafields.write.","security":[{"bearerAuth":[]}],"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."},{"name":"keys","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated namespace.key pairs."}],"responses":{"200":{"description":"Metafields deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/products/{productId}/channels":{"post":{"x-resource-group":"commerce","operationId":"changeCommerceProductChannels","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Publish or unpublish a product","description":"Publishes to and/or unpublishes from sales channels (the online store, Shop, POS and others). List channels with GET /v1/commerce/channels.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string"},"publish":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Channel ids from GET /v1/commerce/channels."},"unpublish":{"type":"array","maxItems":20,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Publication changed","content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string"},"published":{"type":"array","items":{"type":"string"}},"unpublished":{"type":"array","items":{"type":"string"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/collections/{collectionId}/metafields":{"get":{"x-resource-group":"commerce","operationId":"listCommerceCollectionMetafields","tags":["Commerce"],"x-platforms":["shopify"],"summary":"List collection metafields","description":"The collection's metafields as namespace, key, type and value. Needs collections.metafields: WooCommerce keeps custom fields on products only and answers 400 platform_not_supported.","security":[{"bearerAuth":[]}],"parameters":[{"name":"collectionId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Metafields listed","content":{"application/json":{"schema":{"type":"object","properties":{"metafields":{"type":"array","items":{"$ref":"#/components/schemas/CommerceMetafield"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"put":{"x-resource-group":"commerce","operationId":"setCommerceCollectionMetafields","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Set collection metafields","description":"Creates or updates custom fields by namespace and key. Needs collections.metafields: WooCommerce keeps custom fields on products only and answers 400 platform_not_supported.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"collectionId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","metafields"],"properties":{"accountId":{"type":"string"},"metafields":{"type":"array","minItems":1,"maxItems":25,"items":{"$ref":"#/components/schemas/CommerceMetafield"}}}}}}},"responses":{"200":{"description":"Metafields set","content":{"application/json":{"schema":{"type":"object","properties":{"metafields":{"type":"array","items":{"$ref":"#/components/schemas/CommerceMetafield"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"delete":{"x-resource-group":"commerce","operationId":"deleteCommerceCollectionMetafields","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Delete collection metafields","description":"Deletes the collection metafields named in `keys` (comma-separated `namespace.key`, up to 25). Needs collections.metafields: WooCommerce answers 400 platform_not_supported.","security":[{"bearerAuth":[]}],"parameters":[{"name":"collectionId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."},{"name":"keys","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated namespace.key pairs."}],"responses":{"200":{"description":"Metafields deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/collections/{collectionId}/channels":{"post":{"x-resource-group":"commerce","operationId":"changeCommerceCollectionChannels","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Publish or unpublish a collection","description":"Publishes to and/or unpublishes from sales channels (the online store, Shop, POS and others). List channels with GET /v1/commerce/channels.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"collectionId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string"},"publish":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Channel ids from GET /v1/commerce/channels."},"unpublish":{"type":"array","maxItems":20,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Publication changed","content":{"application/json":{"schema":{"type":"object","properties":{"collectionId":{"type":"string"},"published":{"type":"array","items":{"type":"string"}},"unpublished":{"type":"array","items":{"type":"string"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/products/tags":{"post":{"x-resource-group":"commerce","operationId":"changeCommerceProductTags","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Add or remove tags in bulk","description":"Adds and/or removes tags on up to 50 products and reports each product's outcome.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","productIds"],"properties":{"accountId":{"type":"string"},"productIds":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"}},"add":{"type":"array","maxItems":50,"items":{"type":"string"}},"remove":{"type":"array","maxItems":50,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Tags changed","content":{"application/json":{"schema":{"type":"object","properties":{"succeeded":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"message":{"type":"string"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/collections/{collectionId}/reorder":{"post":{"x-resource-group":"commerce","operationId":"reorderCommerceCollectionProducts","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Reorder products in a collection","description":"Moves products to new 0-based positions. Only for collections sorted `manual`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"collectionId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","moves"],"properties":{"accountId":{"type":"string"},"moves":{"type":"array","minItems":1,"maxItems":250,"items":{"type":"object","required":["productId","position"],"properties":{"productId":{"type":"string"},"position":{"type":"integer","minimum":0}}}}}}}}},"responses":{"200":{"description":"Reorder accepted","content":{"application/json":{"schema":{"type":"object","properties":{"pending":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/pages":{"get":{"x-resource-group":"commerce","operationId":"listCommercePages","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"List pages","description":"The store's content pages (Shopify online store pages, WordPress pages), cursor-paginated with `limit`, `cursor` and an optional `query`. Needs pages.read.","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"query","in":"query","required":false,"schema":{"type":"string","maxLength":500},"description":"Platform search syntax, passed through."}],"responses":{"200":{"description":"Pages listed","content":{"application/json":{"schema":{"type":"object","properties":{"pages":{"type":"array","items":{"$ref":"#/components/schemas/CommercePage"}},"nextCursor":{"type":["string","null"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"post":{"x-resource-group":"commerce","operationId":"createCommercePage","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Create a page","description":"Creates a content page from `title`, optional `handle`, `bodyHtml` and `isPublished`, and returns it with status 201. Needs pages.write.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","title"],"properties":{"accountId":{"type":"string"},"title":{"type":"string","minLength":1},"handle":{"type":"string"},"bodyHtml":{"type":"string"},"isPublished":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Page created","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"$ref":"#/components/schemas/CommercePage"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/pages/{pageId}":{"get":{"x-resource-group":"commerce","operationId":"getCommercePage","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Get a page","description":"One content page with its body. Needs pages.read.","security":[{"bearerAuth":[]}],"parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Page fetched","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"$ref":"#/components/schemas/CommercePage"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"patch":{"x-resource-group":"commerce","operationId":"updateCommercePage","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Update a page","description":"Updates the fields you pass (`title`, `handle`, `bodyHtml`, `isPublished`) and returns the page. Needs pages.write.","security":[{"bearerAuth":[]}],"parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string"},"title":{"type":"string","minLength":1},"handle":{"type":"string"},"bodyHtml":{"type":"string"},"isPublished":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Page updated","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"$ref":"#/components/schemas/CommercePage"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"delete":{"x-resource-group":"commerce","operationId":"deleteCommercePage","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Delete a page","description":"Deletes the page from the store. This cannot be undone. Needs pages.write.","security":[{"bearerAuth":[]}],"parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Page deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"pageId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/locations":{"get":{"x-resource-group":"commerce","operationId":"listCommerceLocations","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"List locations","description":"The store's stock locations (warehouses, shops).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Locations listed","content":{"application/json":{"schema":{"type":"object","properties":{"locations":{"type":"array","items":{"$ref":"#/components/schemas/CommerceLocation"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/inventory":{"get":{"x-resource-group":"commerce","operationId":"listCommerceInventory","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Get a product's stock","description":"Stock per variant and location: available, on hand, committed to orders and incoming.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."},{"name":"productId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Stock fetched","content":{"application/json":{"schema":{"type":"object","properties":{"inventory":{"type":"array","items":{"$ref":"#/components/schemas/CommerceInventoryItem"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/products/{productId}/inventory":{"post":{"x-resource-group":"commerce","operationId":"changeCommerceInventory","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Set or adjust stock","description":"`set` makes `quantity` the new available count; `adjust` adds `quantity` (negative to subtract). The variant must be stocked at the location. Answers the product's stock after the change.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","changes"],"properties":{"accountId":{"type":"string"},"mode":{"type":"string","enum":["set","adjust"],"default":"set"},"changes":{"type":"array","minItems":1,"maxItems":250,"items":{"type":"object","required":["variantId","locationId","quantity"],"properties":{"variantId":{"type":"string"},"locationId":{"type":"string"},"quantity":{"type":"integer"}}}}}}}}},"responses":{"200":{"description":"Stock changed","content":{"application/json":{"schema":{"type":"object","properties":{"inventory":{"type":"array","items":{"$ref":"#/components/schemas/CommerceInventoryItem"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/channels":{"get":{"x-resource-group":"commerce","operationId":"listCommerceChannels","tags":["Commerce"],"x-platforms":["shopify"],"summary":"List sales channels","description":"Where products and collections can be published: the online store, Shop, POS and installed channel apps.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Channels listed","content":{"application/json":{"schema":{"type":"object","properties":{"channels":{"type":"array","items":{"$ref":"#/components/schemas/CommerceChannel"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/discounts":{"get":{"x-resource-group":"commerce","operationId":"listCommerceDiscounts","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"List discounts","description":"The store's discounts (Shopify code and automatic discounts, WooCommerce coupons), cursor-paginated with `limit`, `cursor` and an optional `query`. Each discount lists its first 10 codes; `codeCount` has the total. Needs discounts.read.","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"query","in":"query","required":false,"schema":{"type":"string","maxLength":500},"description":"Platform search syntax, passed through."}],"responses":{"200":{"description":"Discounts listed","content":{"application/json":{"schema":{"type":"object","properties":{"discounts":{"type":"array","items":{"$ref":"#/components/schemas/CommerceDiscount"}},"nextCursor":{"type":["string","null"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"post":{"x-resource-group":"commerce","operationId":"createCommerceDiscount","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Create a discount","description":"Creates a code discount (buyers enter a code) or an automatic one (applied at checkout), as a percentage, a fixed amount or free shipping. It applies to every product unless productIds or collectionIds narrow it, and to every buyer.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","title","method","type"],"properties":{"accountId":{"type":"string"},"title":{"type":"string","minLength":1},"method":{"type":"string","enum":["code","automatic"]},"type":{"type":"string","enum":["percentage","fixed_amount","free_shipping"]},"code":{"type":"string","description":"Required for method code."},"percentage":{"type":"number","exclusiveMinimum":0,"maximum":100,"description":"For type percentage, e.g. 15 for 15%."},"amount":{"type":"string","description":"For type fixed_amount, a decimal in the store currency."},"appliesOnEachItem":{"type":"boolean","description":"fixed_amount only: take the amount off each item instead of once per order."},"minimumSubtotal":{"type":["string","null"],"description":"Minimum order subtotal, a decimal in the store currency."},"minimumQuantity":{"type":["integer","null"],"minimum":1},"usageLimit":{"type":["integer","null"],"minimum":1,"description":"Code discounts only: total uses allowed."},"oncePerCustomer":{"type":"boolean","description":"Code discounts only."},"startsAt":{"type":"string","format":"date-time","description":"Defaults to now."},"endsAt":{"type":["string","null"],"format":"date-time"},"productIds":{"type":"array","maxItems":100,"items":{"type":"string"}},"collectionIds":{"type":"array","maxItems":100,"items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Discount created","content":{"application/json":{"schema":{"type":"object","properties":{"discount":{"$ref":"#/components/schemas/CommerceDiscount"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/discounts/{discountId}":{"get":{"x-resource-group":"commerce","operationId":"getCommerceDiscount","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Get a discount","description":"One discount with its value, targets, minimum, usage and schedule. Needs discounts.read.","security":[{"bearerAuth":[]}],"parameters":[{"name":"discountId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Discount fetched","content":{"application/json":{"schema":{"type":"object","properties":{"discount":{"$ref":"#/components/schemas/CommerceDiscount"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"patch":{"x-resource-group":"commerce","operationId":"updateCommerceDiscount","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Update a discount","description":"Changes a percentage, fixed-amount or free-shipping discount. Buy-X-get-Y and app discounts are read-only here.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"discountId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"Required for method code."},"percentage":{"type":"number","exclusiveMinimum":0,"maximum":100,"description":"For type percentage, e.g. 15 for 15%."},"amount":{"type":"string","description":"For type fixed_amount, a decimal in the store currency."},"appliesOnEachItem":{"type":"boolean","description":"fixed_amount only: take the amount off each item instead of once per order."},"minimumSubtotal":{"type":["string","null"],"description":"Minimum order subtotal, a decimal in the store currency."},"minimumQuantity":{"type":["integer","null"],"minimum":1},"usageLimit":{"type":["integer","null"],"minimum":1,"description":"Code discounts only: total uses allowed."},"oncePerCustomer":{"type":"boolean","description":"Code discounts only."},"startsAt":{"type":"string","format":"date-time","description":"Defaults to now."},"endsAt":{"type":["string","null"],"format":"date-time"}}}}}},"responses":{"200":{"description":"Discount updated","content":{"application/json":{"schema":{"type":"object","properties":{"discount":{"$ref":"#/components/schemas/CommerceDiscount"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"delete":{"x-resource-group":"commerce","operationId":"deleteCommerceDiscount","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Delete a discount","description":"Deletes the discount; its codes stop working at checkout. This cannot be undone. Needs discounts.write.","security":[{"bearerAuth":[]}],"parameters":[{"name":"discountId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Discount deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"discountId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/discounts/{discountId}/state":{"post":{"x-resource-group":"commerce","operationId":"setCommerceDiscountActive","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Activate or deactivate a discount","description":"Deactivating ends the discount now; activating starts it now.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"discountId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","active"],"properties":{"accountId":{"type":"string"},"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Discount state changed","content":{"application/json":{"schema":{"type":"object","properties":{"discount":{"$ref":"#/components/schemas/CommerceDiscount"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/discounts/{discountId}/codes":{"post":{"x-resource-group":"commerce","operationId":"addCommerceDiscountCodes","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Add codes to a discount","description":"Adds up to 250 more codes to a code discount, for example one per influencer. The platform adds them in the background. Needs discounts.codes, which WooCommerce stores do not have.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"discountId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","codes"],"properties":{"accountId":{"type":"string"},"codes":{"type":"array","minItems":1,"maxItems":250,"items":{"type":"string"}}}}}}},"responses":{"202":{"description":"Codes queued","content":{"application/json":{"schema":{"type":"object","properties":{"pending":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/redirects":{"get":{"x-resource-group":"commerce","operationId":"listCommerceRedirects","tags":["Commerce"],"x-platforms":["shopify"],"summary":"List URL redirects","description":"The store's URL redirects (old path to new target), cursor-paginated with `limit`, `cursor` and an optional `query` on the path. Shopify only. Needs navigation.read.","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"query","in":"query","required":false,"schema":{"type":"string","maxLength":500},"description":"Platform search syntax, passed through."}],"responses":{"200":{"description":"Redirects listed","content":{"application/json":{"schema":{"type":"object","properties":{"redirects":{"type":"array","items":{"$ref":"#/components/schemas/CommerceRedirect"}},"nextCursor":{"type":["string","null"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"post":{"x-resource-group":"commerce","operationId":"createCommerceRedirect","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Create a URL redirect","description":"Creates a redirect from `path` (starting with `/`) to `target` (a path or a full URL) and returns it with status 201. Shopify only. Needs navigation.write.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","path","target"],"properties":{"accountId":{"type":"string"},"path":{"type":"string","description":"The old path, starting with /."},"target":{"type":"string","description":"Where to send visitors: a path or a full URL."}}}}}},"responses":{"201":{"description":"Redirect created","content":{"application/json":{"schema":{"type":"object","properties":{"redirect":{"$ref":"#/components/schemas/CommerceRedirect"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/redirects/{redirectId}":{"patch":{"x-resource-group":"commerce","operationId":"updateCommerceRedirect","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Update a URL redirect","description":"Changes the redirect's `path` and/or `target`. Shopify only. Needs navigation.write.","security":[{"bearerAuth":[]}],"parameters":[{"name":"redirectId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId"],"properties":{"accountId":{"type":"string"},"path":{"type":"string"},"target":{"type":"string"}}}}}},"responses":{"200":{"description":"Redirect updated","content":{"application/json":{"schema":{"type":"object","properties":{"redirect":{"$ref":"#/components/schemas/CommerceRedirect"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"delete":{"x-resource-group":"commerce","operationId":"deleteCommerceRedirect","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Delete a URL redirect","description":"Deletes the redirect; the old path answers 404 again. Shopify only. Needs navigation.write.","security":[{"bearerAuth":[]}],"parameters":[{"name":"redirectId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Redirect deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"redirectId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/menus":{"get":{"x-resource-group":"commerce","operationId":"listCommerceMenus","tags":["Commerce"],"x-platforms":["shopify"],"summary":"List navigation menus","description":"The store's navigation menus with their items. Shopify only. Needs navigation.read.","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Menus listed","content":{"application/json":{"schema":{"type":"object","properties":{"menus":{"type":"array","items":{"$ref":"#/components/schemas/CommerceMenu"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"post":{"x-resource-group":"commerce","operationId":"createCommerceMenu","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Create a navigation menu","description":"Creates a navigation menu from `title`, `handle` and up to 100 `items`, and returns it with status 201. Shopify only. Needs navigation.write.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","title","handle","items"],"properties":{"accountId":{"type":"string"},"title":{"type":"string"},"handle":{"type":"string"},"items":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/CommerceMenuItemInput"}}}}}}},"responses":{"201":{"description":"Menu created","content":{"application/json":{"schema":{"type":"object","properties":{"menu":{"$ref":"#/components/schemas/CommerceMenu"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/menus/{menuId}":{"get":{"x-resource-group":"commerce","operationId":"getCommerceMenu","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Get a navigation menu","description":"One navigation menu with its nested items. Shopify only. Needs navigation.read.","security":[{"bearerAuth":[]}],"parameters":[{"name":"menuId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Menu fetched","content":{"application/json":{"schema":{"type":"object","properties":{"menu":{"$ref":"#/components/schemas/CommerceMenu"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"put":{"x-resource-group":"commerce","operationId":"updateCommerceMenu","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Replace a navigation menu","description":"Replaces the title and the whole item tree.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"menuId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","title","items"],"properties":{"accountId":{"type":"string"},"title":{"type":"string"},"handle":{"type":"string"},"items":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/CommerceMenuItemInput"}}}}}}},"responses":{"200":{"description":"Menu updated","content":{"application/json":{"schema":{"type":"object","properties":{"menu":{"$ref":"#/components/schemas/CommerceMenu"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"delete":{"x-resource-group":"commerce","operationId":"deleteCommerceMenu","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Delete a navigation menu","description":"Deletes the navigation menu. Shopify only. Needs navigation.write.","security":[{"bearerAuth":[]}],"parameters":[{"name":"menuId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Menu deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"menuId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/metaobject-definitions":{"get":{"x-resource-group":"commerce","operationId":"listCommerceMetaobjectDefinitions","tags":["Commerce"],"x-platforms":["shopify"],"summary":"List metaobject definitions","description":"The custom content types defined on the store and their fields.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Definitions listed","content":{"application/json":{"schema":{"type":"object","properties":{"definitions":{"type":"array","items":{"$ref":"#/components/schemas/CommerceMetaobjectDefinition"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/metaobjects":{"get":{"x-resource-group":"commerce","operationId":"listCommerceMetaobjects","tags":["Commerce"],"x-platforms":["shopify"],"summary":"List metaobjects of a type","description":"The metaobjects of one `type` (a definition handle from GET /v1/commerce/metaobject-definitions), cursor-paginated with `limit` and `cursor`. Shopify only. Needs metaobjects.read.","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."},{"name":"type","in":"query","required":true,"schema":{"type":"string"},"description":"Definition type from GET /v1/commerce/metaobject-definitions."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Metaobjects listed","content":{"application/json":{"schema":{"type":"object","properties":{"metaobjects":{"type":"array","items":{"$ref":"#/components/schemas/CommerceMetaobject"}},"nextCursor":{"type":["string","null"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"post":{"x-resource-group":"commerce","operationId":"createCommerceMetaobject","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Create a metaobject","description":"Creates a metaobject of `type` with its `fields` (key and string value, up to 100) and an optional `handle`, and returns it with status 201. Shopify only. Needs metaobjects.write.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","type","fields"],"properties":{"accountId":{"type":"string"},"type":{"type":"string"},"handle":{"type":"string"},"fields":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["key","value"],"properties":{"key":{"type":"string"},"value":{"type":"string"}}}}}}}}},"responses":{"201":{"description":"Metaobject created","content":{"application/json":{"schema":{"type":"object","properties":{"metaobject":{"$ref":"#/components/schemas/CommerceMetaobject"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/metaobjects/{metaobjectId}":{"get":{"x-resource-group":"commerce","operationId":"getCommerceMetaobject","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Get a metaobject","description":"One metaobject with its fields. Shopify only. Needs metaobjects.read.","security":[{"bearerAuth":[]}],"parameters":[{"name":"metaobjectId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Metaobject fetched","content":{"application/json":{"schema":{"type":"object","properties":{"metaobject":{"$ref":"#/components/schemas/CommerceMetaobject"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"patch":{"x-resource-group":"commerce","operationId":"updateCommerceMetaobject","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Update a metaobject","description":"Sets the given field values; fields left out keep theirs.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"metaobjectId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","fields"],"properties":{"accountId":{"type":"string"},"handle":{"type":"string"},"fields":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["key","value"],"properties":{"key":{"type":"string"},"value":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Metaobject updated","content":{"application/json":{"schema":{"type":"object","properties":{"metaobject":{"$ref":"#/components/schemas/CommerceMetaobject"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"delete":{"x-resource-group":"commerce","operationId":"deleteCommerceMetaobject","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Delete a metaobject","description":"Deletes the metaobject. References to it from metafields stop resolving. Shopify only. Needs metaobjects.write.","security":[{"bearerAuth":[]}],"parameters":[{"name":"metaobjectId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Metaobject deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"metaobjectId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/markets":{"get":{"x-resource-group":"commerce","operationId":"listCommerceMarkets","tags":["Commerce"],"x-platforms":["shopify"],"summary":"List markets","description":"The regions the store sells to, each with its own currency and pricing.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Markets listed","content":{"application/json":{"schema":{"type":"object","properties":{"markets":{"type":"array","items":{"$ref":"#/components/schemas/CommerceMarket"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/price-lists":{"get":{"x-resource-group":"commerce","operationId":"listCommercePriceLists","tags":["Commerce"],"x-platforms":["shopify"],"summary":"List price lists","description":"Price lists hold fixed prices per variant for a market.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Price lists listed","content":{"application/json":{"schema":{"type":"object","properties":{"priceLists":{"type":"array","items":{"$ref":"#/components/schemas/CommercePriceList"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/price-lists/{priceListId}/prices":{"put":{"x-resource-group":"commerce","operationId":"setCommercePriceListPrices","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Set fixed prices","description":"Sets fixed prices for variants in the price list's currency, overriding the converted price in that market.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"priceListId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","prices"],"properties":{"accountId":{"type":"string"},"prices":{"type":"array","minItems":1,"maxItems":250,"items":{"type":"object","required":["variantId","price"],"properties":{"variantId":{"type":"string"},"price":{"type":"string","description":"Decimal in the price list currency."},"compareAtPrice":{"type":["string","null"]}}}}}}}}},"responses":{"200":{"description":"Prices set","content":{"application/json":{"schema":{"type":"object","properties":{"priceListId":{"type":"string"},"updated":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}},"delete":{"x-resource-group":"commerce","operationId":"deleteCommercePriceListPrices","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Remove fixed prices","description":"The variants go back to the market's converted price.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"priceListId","in":"path","required":true,"schema":{"type":"string"},"description":"Platform-native id."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."},{"name":"variantIds","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated ids."}],"responses":{"200":{"description":"Prices removed","content":{"application/json":{"schema":{"type":"object","properties":{"priceListId":{"type":"string"},"deleted":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/marketing-activities":{"put":{"x-resource-group":"commerce","operationId":"upsertCommerceMarketingActivity","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Record a marketing activity","description":"Creates or updates (by `remoteId`) an activity in the store's Marketing section, so the merchant sees a post, ad or message you ran for them, with its link and UTM parameters for attribution. Use your own id (for example the Zernio post or ad id) as `remoteId`.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","remoteId","title","url","tactic","channel","status"],"properties":{"accountId":{"type":"string"},"remoteId":{"type":"string","maxLength":255},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"previewImageUrl":{"type":"string","format":"uri"},"utm":{"type":"object","required":["campaign","source","medium"],"properties":{"campaign":{"type":"string"},"source":{"type":"string"},"medium":{"type":"string"}}},"tactic":{"type":"string","enum":["ad","post","message","newsletter","link","affiliate","retargeting","loyalty","seo"]},"channel":{"type":"string","enum":["social","search","display","email","referral"]},"status":{"type":"string","enum":["active","inactive","paused","scheduled"]},"budget":{"type":"object","required":["type","amount"],"properties":{"type":{"type":"string","enum":["daily","lifetime"]},"amount":{"type":"string","description":"Decimal in the store currency."}}},"adSpend":{"type":"string","description":"Decimal in the store currency."},"startedAt":{"type":"string","format":"date-time"},"endedAt":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"Activity recorded","content":{"application/json":{"schema":{"type":"object","properties":{"marketingActivity":{"type":"object","properties":{"id":{"type":"string"},"remoteId":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/marketing-activities/{remoteId}":{"delete":{"x-resource-group":"commerce","operationId":"deleteCommerceMarketingActivity","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Delete a marketing activity","description":"Deletes the marketing activity you created with PUT /v1/commerce/marketing-activities, identified by the `remoteId` you gave it. Shopify only. Needs marketing.write.","security":[{"bearerAuth":[]}],"parameters":[{"name":"remoteId","in":"path","required":true,"schema":{"type":"string"},"description":"The remoteId given when recording it."},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Activity deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"remoteId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/marketing-activities/{remoteId}/engagements":{"post":{"x-resource-group":"commerce","operationId":"addCommerceMarketingEngagement","tags":["Commerce"],"x-platforms":["shopify"],"summary":"Report daily engagement","description":"Reports one day's numbers for an activity (UTC day), shown next to it in the store's Marketing section.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"remoteId","in":"path","required":true,"schema":{"type":"string"},"description":"The remoteId given when recording it."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","date"],"properties":{"accountId":{"type":"string"},"date":{"type":"string","format":"date"},"impressions":{"type":"integer","minimum":0},"views":{"type":"integer","minimum":0},"clicks":{"type":"integer","minimum":0},"shares":{"type":"integer","minimum":0},"likes":{"type":"integer","minimum":0},"comments":{"type":"integer","minimum":0},"adSpend":{"type":"string","description":"Decimal in the store currency."}}}}}},"responses":{"201":{"description":"Engagement recorded","content":{"application/json":{"schema":{"type":"object","properties":{"remoteId":{"type":"string"},"recorded":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"The platform denied access: reconnect the store to grant the missing permissions.","description":"The store has not granted this permission, or the token was revoked (code insufficient_permissions). Reconnect the store to grant the latest permissions; GET /v1/commerce/store lists what the current grant allows."},"404":{"description":"Account not found (code account_not_found) or the resource was not found (code product_not_found or resource_not_found)."},"429":{"x-summary":"Zernio or the platform rate limited the request: retry later.","description":"Rate limited, either by Zernio or by the platform. Retry later."}}}},"/v1/commerce/catalog-syncs":{"get":{"x-resource-group":"commerce","operationId":"listCommerceCatalogSyncs","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"List catalog syncs","description":"The ad-platform catalogs this store is kept in sync with.","security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Connected store SocialAccount id."}],"responses":{"200":{"description":"Catalog syncs listed","content":{"application/json":{"schema":{"type":"object","properties":{"catalogSyncs":{"type":"array","items":{"$ref":"#/components/schemas/CommerceCatalogSync"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Account not found or not accessible (code account_not_found)."}}},"post":{"x-resource-group":"commerce","operationId":"createCommerceCatalogSync","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Sync a store into a Meta catalog","description":"Keeps a Meta product catalog in sync with the store, for catalog ads (`goal: catalog_sales`) and Shops.\n\n### How the sync runs\n\n1. The first full run starts right away in the background; `runStatus` and the item counts report its outcome.\n2. After that, product changes on the store update the catalog within minutes.\n3. A daily full run removes items for products or variants the store no longer has.\n\nEvery active product variant that is published to the online store and has an image becomes a catalog item, grouped by product (`item_group_id`).\n\nItems are namespaced to the store, so a catalog can take several stores and a run never touches items it did not create.\n\n### Catalog account\n\n`catalogAccountId` is a connected facebook, instagram or metaads account whose Meta login can manage the catalog (the catalog_management permission). Find catalogs with `GET /v1/ads/catalogs`.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","catalogAccountId","catalogId"],"properties":{"accountId":{"type":"string","description":"The store SocialAccount id."},"catalogAccountId":{"type":"string"},"catalogId":{"type":"string","pattern":"^\\d+$","description":"Meta product catalog id."}}}}}},"responses":{"202":{"description":"Sync created; the first run is queued","content":{"application/json":{"schema":{"type":"object","properties":{"catalogSync":{"$ref":"#/components/schemas/CommerceCatalogSync"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The Meta login cannot manage the catalog (code insufficient_permissions)."},"404":{"description":"Account or catalog not found (code account_not_found or resource_not_found)."},"409":{"description":"The store already syncs to that catalog (code catalog_sync_conflict)."}}}},"/v1/commerce/catalog-syncs/{syncId}":{"get":{"x-resource-group":"commerce","operationId":"getCommerceCatalogSync","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Get a catalog sync","description":"One catalog sync with the status and counts of its last run (`itemsSent`, `itemsSkipped`, `itemsDeleted`, `lastError`). Poll it after POST /v1/commerce/catalog-syncs/{syncId}/run to follow a run.","security":[{"bearerAuth":[]}],"parameters":[{"name":"syncId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Catalog sync fetched","content":{"application/json":{"schema":{"type":"object","properties":{"catalogSync":{"$ref":"#/components/schemas/CommerceCatalogSync"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Catalog sync not found (code resource_not_found)."}}},"delete":{"x-resource-group":"commerce","operationId":"deleteCommerceCatalogSync","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Stop a catalog sync","description":"Stops syncing. Items already in the catalog stay there.","security":[{"bearerAuth":[]}],"parameters":[{"name":"syncId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Catalog sync stopped","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"syncId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Catalog sync not found (code resource_not_found)."}}}},"/v1/commerce/catalog-syncs/{syncId}/run":{"post":{"x-resource-group":"commerce","operationId":"runCommerceCatalogSync","tags":["Commerce"],"x-platforms":["shopify","woocommerce"],"summary":"Run a catalog sync now","description":"Queues a full run. Poll GET /v1/commerce/catalog-syncs/{syncId} for the outcome.","security":[{"bearerAuth":[]}],"parameters":[{"name":"syncId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"Run queued","content":{"application/json":{"schema":{"type":"object","properties":{"catalogSync":{"$ref":"#/components/schemas/CommerceCatalogSync"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Catalog sync not found (code resource_not_found)."},"409":{"description":"A run is already in progress (code catalog_sync_conflict)."}}}},"/v1/verify/verifications":{"post":{"x-resource-group":"telephony","operationId":"createVerification","tags":["Verify"],"summary":"Send a verification code","description":"Generate a one-time code, deliver it to the recipient, and store only its hash. Check the user-typed code with POST /v1/verify/verifications/{verificationId}/check.\n\n### Resends\n\nRe-POSTing for the same (channel, to) while a verification is active RESENDS a fresh code on the existing verification (200 with `resend: true`) instead of creating a new one.\n\nResends are limited to one per 60 seconds (429 with `retryAfterSeconds` inside the cooldown). The stored brandName/codeLength/ttlMinutes win on a resend.\n\n### Channels\n\nCodes deliver from a number on your account (`from` optional when you own exactly one number on the channel), always with a fixed template.\n\n- `sms`: from an SMS-enabled number. Each accepted send bills one verification fee plus the standard message rate.\n- `whatsapp`: from a connected WhatsApp number, as a Meta AUTHENTICATION template with a copy-code button. Each accepted send bills one verification fee; Meta bills its authentication rate to your WhatsApp Business Account.\n\n### WhatsApp template\n\nThe first WhatsApp verification on a WhatsApp Business Account creates the `zernio_verify_code` template there. It answers 422 `template_pending` until Meta approves it (usually minutes; retry after `retryAfterSeconds`).\n\nMeta fixes the message text, so `brandName` is not shown and the code's validity is not stated in the message (`ttlMinutes` is still enforced).\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["channel","to"],"properties":{"channel":{"type":"string","enum":["sms","whatsapp"]},"to":{"type":"string","description":"E.164 phone number. WhatsApp only delivers to a phone number, never to a username."},"from":{"type":"string","description":"The number on your account to send from: an SMS-enabled number for `sms`, a connected WhatsApp number for `whatsapp`. Defaults to your only number on that channel."},"brandName":{"type":"string","maxLength":30,"description":"Your app or business name, rendered in the SMS message. Defaults to your account name. Not shown on WhatsApp, where Meta fixes the message and shows your WhatsApp display name. Letters, numbers, and basic punctuation only."},"codeLength":{"type":"integer","minimum":4,"maximum":8,"default":6},"ttlMinutes":{"type":"integer","minimum":1,"maximum":15,"default":10}}}}}},"responses":{"200":{"description":"Active verification found: a fresh code was resent (`resend: true`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"201":{"description":"Verification created and the code sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/BalanceRequired"},"403":{"description":"Verifications require usage-based billing."},"404":{"description":"The 'from' number is not an SMS-enabled (sms) or connected WhatsApp (whatsapp) number on this account."},"409":{"description":"The recipient has opted out of messages from your number."},"422":{"x-summary":"The channel cannot send verifications: link a number, wait for the WhatsApp template review, fix the rejected template, or reconnect the number.","description":"No number on your account for the channel (code linked_account_required), or, on whatsapp, the verification template is still in Meta review (code template_pending, retry after `retryAfterSeconds`) or was rejected, paused or disabled by Meta (code template_rejected, `details.status` and `details.reason` say why), or the WhatsApp number needs reconnection (code invalid_resource_state)."},"429":{"description":"Resend cooldown or a send cap was hit; `retryAfterSeconds` says when to retry."}}}},"/v1/verify/verifications/{verificationId}":{"get":{"x-resource-group":"telephony","operationId":"getVerification","tags":["Verify"],"summary":"Get a verification","description":"Current state of a verification. `status` is effective (a pending code\npast its expiry reads as `expired`). Verification records are deleted\n24 hours after creation, after which this returns 404.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"verificationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The verification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Verification not found (or already reaped)."}}}},"/v1/verify/verifications/{verificationId}/check":{"post":{"x-resource-group":"telephony","operationId":"checkVerification","tags":["Verify"],"summary":"Check a verification code","description":"Verify the code the user typed. Wrong, expired, and exhausted codes\nanswer 200 with `valid: false` and the settled `status`. Only an\nunknown id is a 404. A correct code consumes the verification\n(single-use, `status: approved`) and fires the `verification.approved`\nwebhook; the 5th wrong attempt settles it as `max_attempts_reached`\nand fires `verification.failed`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"verificationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","pattern":"^\\d{4,8}$"}}}}}},"responses":{"200":{"description":"Check result: the verification plus `valid`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Verification"},{"type":"object","properties":{"valid":{"type":"boolean"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Verification not found (or already reaped)."}}}},"/v1/ads/pixels":{"get":{"x-resource-group":"ads","operationId":"listTikTokAdPixels","summary":"List TikTok ad pixels","description":"Lists pixels and their supported optimization events for a connected TikTok Ads account. The advertiser defaults to the first advertiser on the connection. Reconnect if Pixel Management permission has not been granted.","tags":["Ad Accounts"],"x-platforms":["tiktok"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"description":"Zernio SocialAccount ID."},{"name":"adAccountId","in":"query","schema":{"type":"string"},"description":"Platform ad account ID (TikTok advertiser id, digits only). Defaults to the first advertiser on the connection."},{"name":"advertiserId","in":"query","deprecated":true,"schema":{"type":"string"},"description":"Alias of adAccountId, kept for existing callers"},{"name":"code","in":"query","schema":{"type":"string"},"description":"Filter by a Pixel Code."}],"responses":{"200":{"description":"TikTok pixels.","content":{"application/json":{"schema":{"type":"object","properties":{"advertiserId":{"type":"string"},"pixels":{"type":"array","items":{"type":"object","properties":{"pixelId":{"type":"string"},"pixelCode":{"type":"string"},"name":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"eventDetails":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"optimizationEvent":{"type":["string","null"]},"custom":{"type":"boolean"}}}}}}}}},"example":{"advertiserId":"7330955083452284929","pixels":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Ads access required."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"x-summary":"The Pixel Management permission is missing: reconnect TikTok Ads to grant it.","description":"Pixel Management permission is missing (code reconnect_required). Reconnect TikTok Ads to grant it."}}}},"/v1/ads/partnership-content":{"get":{"x-resource-group":"ads","operationId":"listPartnershipAdContent","summary":"List partnership ad content","description":"Lists a creator's Instagram posts you can run as Partnership Ads, looked up by creator or post link (private beta).\n\nLists creator Instagram posts available to the advertiser for Partnership Ads. Supply creatorUsername or postUrl. Requires instagram_branded_content_ads_brand permission and an advertiser Instagram Business Account.\n","tags":["Ad Creatives"],"x-platforms":["meta"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"description":"Zernio SocialAccount ID."},{"name":"creatorUsername","in":"query","schema":{"type":"string"},"description":"Creator username. Required unless postUrl is supplied."},{"name":"postUrl","in":"query","schema":{"type":"string","format":"uri"},"description":"Instagram post permalink. Required unless creatorUsername is supplied."},{"name":"onlyAllowlisted","in":"query","schema":{"type":"boolean"},"description":"Return only creators with account-level permission."}],"responses":{"200":{"description":"Advertisable Instagram media.","content":{"application/json":{"schema":{"type":"object","properties":{"media":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"permalink":{"type":"string"},"ownerId":{"type":"string"},"hasPermissionForPartnershipAd":{"type":"boolean"},"isCreatorAllowlisted":{"type":"boolean"},"eligibilityErrors":{"type":"array","items":{"type":"string"}},"recommendedCampaignObjectives":{"type":"array","items":{"type":"string"}}}}}}},"example":{"media":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the account lacks private beta access for partnership operations.","description":"Ads access required. Partnership operations also require private beta access."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"description":"The advertiser Instagram Business Account could not be resolved."}}}},"/v1/ads/partnership-permissions":{"get":{"x-resource-group":"ads","operationId":"listPartnershipAdPermissions","summary":"List partnership permissions","description":"Lists the creators who have granted, or have pending, permission for your Instagram account to run Partnership Ads with them (private beta).\n\nLists granted or pending creator permissions for the advertiser Instagram Business Account. Requires instagram_branded_content_ads_brand permission.\n","tags":["Ad Creatives"],"x-platforms":["meta"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"description":"Zernio SocialAccount ID."},{"name":"creatorUsername","in":"query","schema":{"type":"string"},"description":"Filter by creator username."}],"responses":{"200":{"description":"Partnership permissions.","content":{"application/json":{"schema":{"type":"object","properties":{"permissions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"permissionType":{"type":"string"},"status":{"type":"string"}}}}}},"example":{"permissions":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the account lacks private beta access for partnership operations.","description":"Ads access required. Partnership operations also require private beta access."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"description":"The advertiser Instagram Business Account could not be resolved."}}},"post":{"x-resource-group":"ads","operationId":"setPartnershipAdPermission","summary":"Set partnership permission","description":"Asks a creator for permission to run Partnership Ads with their content, or revokes it (private beta).\n\nRequests permission from a creator or revokes it when revoke is true. Requests require the creator to approve in Instagram. Requires instagram_branded_content_ads_brand permission.\n","tags":["Ad Creatives"],"x-platforms":["meta"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","creatorUsername"],"properties":{"accountId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"creatorUsername":{"type":"string","minLength":1},"revoke":{"type":"boolean"}}},"example":{"accountId":"507f1f77bcf86cd799439011","creatorUsername":"example_creator","revoke":false}}}},"responses":{"200":{"description":"Partnership permission state.","content":{"application/json":{"schema":{"type":"object","properties":{"permission":{"type":"object","properties":{"id":{"type":"string"},"permissionType":{"type":"string"},"status":{"type":"string"}}}}},"example":{"permission":{"id":"123456789","permissionType":"AD","status":"PENDING"}}}}},"201":{"description":"Partnership permission state.","content":{"application/json":{"schema":{"type":"object","properties":{"permission":{"type":"object","properties":{"id":{"type":"string"},"permissionType":{"type":"string"},"status":{"type":"string"}}}}},"example":{"permission":{"id":"123456789","permissionType":"AD","status":"PENDING"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"x-summary":"Ads access is missing or the account lacks private beta access for partnership operations.","description":"Ads access required. Partnership operations also require private beta access."},"404":{"$ref":"#/components/responses/AccountUnavailable"},"409":{"$ref":"#/components/responses/AccountConnectionRequired"},"422":{"description":"The advertiser Instagram Business Account could not be resolved."}}}},"/v1/media/prepare":{"post":{"x-resource-group":"publishing","operationId":"prepareMedia","tags":["Media"],"summary":"Prepare media for a platform","description":"Turn any image or video into a version the target platform accepts, using the same per-platform processing Zernio runs before publishing.\n\nEach team can prepare up to 60 files per hour; past that the endpoint answers 429 with `retryAfterSeconds`.\n\n### Video, per target\n\n- `instagram`, `facebook_reel`: re-encode to H.264 Main 4.1, 30 fps, 1080 wide (HDR sources only get the size step, so they are not flattened to SDR).\n- `instagram_story`: re-encodes a video over 100MB to fit 60 seconds and 100MB.\n- `facebook_story`: reframes anything wider than 9:16 onto a 1080x1920 canvas with a blurred background (Facebook otherwise publishes such stories with 0 seconds of video and no error).\n- `threads`: re-encodes to the conservative H.264 Baseline profile Threads processes reliably.\n- `bluesky`: re-encodes to 1080 wide and at most 180 seconds, then compresses under 50MB if the result is still larger.\n- `telegram`: compresses to 50MB and moves the index to the start of the file.\n- Other targets compress only when the file is over the platform limit.\n\n### Images\n\nImages are converted to a format the platform ingests (Instagram takes only JPEG; LinkedIn and Google Business reject WebP and AVIF) and compressed under its size limit.\n\n- `telegram` also fits the width plus height limit.\n- `googlebusiness` enlarges images under its minimum size.\n\n### Result\n\nWhen the file already complies, `changed` is false and `url` is the input URL (after redirects). Otherwise `url` points to the prepared file in Zernio storage, kept under the same retention as uploaded media.\n\nThe request is synchronous: a long video can take a few minutes.\n\n- Videos over 200MB are refused with 413.\n- A video URL whose host sends no Content-Length is refused with 400.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","target"],"properties":{"url":{"type":"string","format":"uri","description":"Public http(s) URL of the image or video.","example":"https://example.com/clip.mov"},"target":{"type":"string","enum":["instagram","instagram_story","facebook","facebook_reel","facebook_story","threads","tiktok","linkedin","twitter","bluesky","pinterest","reddit","snapchat","telegram","googlebusiness","youtube_thumbnail"],"description":"Where the media will be published. `twitter`, `googlebusiness` and `youtube_thumbnail` take images only; `facebook_reel` takes videos only.","example":"facebook_story"}}}}}},"responses":{"200":{"description":"Prepared media","content":{"application/json":{"schema":{"type":"object","required":["target","url","changed","mediaType","originalSize","outputSize"],"properties":{"target":{"type":"string"},"url":{"type":"string","format":"uri","description":"URL to publish: the prepared file, or the input URL when nothing needed to change."},"changed":{"type":"boolean","description":"Whether the media was processed."},"mediaType":{"type":"string","enum":["image","video"]},"originalSize":{"type":["integer","null"],"description":"Input size in bytes, null when the host does not report it."},"outputSize":{"type":["integer","null"],"description":"Size of the returned file in bytes."}}},"example":{"target":"facebook_story","url":"https://media.zernio.com/media/1761100000000_ab12cd_clip_story.mp4","changed":true,"mediaType":"video","originalSize":48211337,"outputSize":31877210}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ResourceGroupForbidden"},"413":{"description":"The video is over the 200MB this endpoint prepares."},"422":{"description":"The media could not be processed (for example a corrupt file)."},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/changelog":{"get":{"x-resource-group":"public","operationId":"listChangelog","tags":["Changelog"],"summary":"List API changelog entries","security":[],"description":"The API changelog, newest first. No API key needed; one address may make 120 requests a minute.\n\nEach entry is what the `api.changelog.published` webhook delivered:\n\n- `message`: the announcement\n- `impact`: its impact on existing integrations\n- `changes`: the deterministic diff of the OpenAPI spec (operations and schemas added, removed and modified) for automation to act on\n\nPage with `before` set to the previous page's `nextCursor`.\n","parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["new_feature","breaking_change","improvement","deprecation","minor"]},"description":"Only entries of this type."},{"name":"impact","in":"query","required":false,"schema":{"type":"string","enum":["none","additive","action_required"]},"description":"Only entries with this impact. `action_required` lists the changes an integration may need to act on."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-z0-9-]+$"},"description":"Only entries tagged with this platform or area slug (see `platforms` on the entry). One slug per request.","example":"whatsapp"},{"name":"before","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only entries published strictly before this instant. Pass the previous page's `nextCursor`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Changelog entries","content":{"application/json":{"schema":{"type":"object","required":["entries","nextCursor"],"properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/ApiChangelogEntry"}},"nextCursor":{"type":["string","null"],"format":"date-time","description":"`before` value for the next page, or null when this page was not full."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/creator-campaigns":{"post":{"x-resource-group":"creator_campaigns","operationId":"createCreatorCampaign","tags":["Creator Campaigns"],"summary":"Create creator campaign","description":"Creates a campaign in `draft`. Creators are paid for verified performance of the posts they\nsubmit: Zernio tracks each post through a tracking window, scores its authenticity and records\nevery earning in a ledger. Activate the campaign to start accepting submissions.\n\nCreator campaigns run on usage-based billing; a workspace not on it gets 403\n`feature_not_available`. `profileId` must be a profile this key can reach, otherwise 404.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCreatorCampaignRequest"}}}},"responses":{"201":{"description":"Campaign created","content":{"application/json":{"schema":{"type":"object","required":["campaign"],"properties":{"campaign":{"$ref":"#/components/schemas/CreatorCampaign"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"},"409":{"$ref":"#/components/responses/IdempotencyKeyInFlight"},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"}}},"get":{"x-resource-group":"creator_campaigns","operationId":"listCreatorCampaigns","tags":["Creator Campaigns"],"summary":"List creator campaigns","description":"Lists the team's campaigns in the profiles this key can reach, newest first.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["draft","active","paused","closed"]}},{"name":"profileId","in":"query","schema":{"type":"string"},"description":"Only campaigns in this profile."},{"name":"q","in":"query","schema":{"type":"string","minLength":1,"maxLength":100},"description":"Only campaigns whose name or brand name contains this text, ignoring case."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"skip","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Campaigns","content":{"application/json":{"schema":{"type":"object","required":["campaigns","total"],"properties":{"campaigns":{"type":"array","items":{"$ref":"#/components/schemas/CreatorCampaign"}},"total":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"}}}},"/v1/creator-campaigns/{campaignId}":{"get":{"x-resource-group":"creator_campaigns","operationId":"getCreatorCampaign","tags":["Creator Campaigns"],"summary":"Get creator campaign","description":"Returns the campaign with its budget consumption, participant count and submission counts.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."}],"responses":{"200":{"description":"Campaign","content":{"application/json":{"schema":{"type":"object","required":["campaign"],"properties":{"campaign":{"$ref":"#/components/schemas/CreatorCampaign"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"}}},"patch":{"x-resource-group":"creator_campaigns","operationId":"updateCreatorCampaign","tags":["Creator Campaigns"],"summary":"Update creator campaign","description":"Updates any subset of the campaign's settings. `economics` (and with it the campaign type)\ncan only change while the campaign is a draft; afterwards that answers 409, and a live campaign's\nbudget is raised with `POST /v1/creator-campaigns/{campaignId}/budget`. An empty body\nanswers 400.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCreatorCampaignRequest"}}}},"responses":{"200":{"description":"Campaign updated","content":{"application/json":{"schema":{"type":"object","required":["campaign"],"properties":{"campaign":{"$ref":"#/components/schemas/CreatorCampaign"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"},"409":{"$ref":"#/components/responses/CreatorCampaignConflict"}}}},"/v1/creator-campaigns/{campaignId}/budget":{"post":{"x-resource-group":"creator_campaigns","operationId":"raiseCreatorCampaignBudget","tags":["Creator Campaigns"],"summary":"Raise creator campaign budget","description":"Raises the budget of a campaign that is `draft`, `active` or `paused`.\n\nOnly the budget changes. The pay terms stay as creators joined them, which `PATCH` refuses to change once the campaign is live.\n\n- The new `budgetCents` must be above the current budget, otherwise 400 `invalid_field_value`.\n- When it is also above what the campaign has spent, `budgetExhaustedAt` is cleared and earnings that stopped at the old budget resume.\n- A closed campaign answers 409 `invalid_resource_state`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."},{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["budgetCents"],"properties":{"budgetCents":{"type":"integer","minimum":1,"description":"The new total budget in cents."}}}}}},"responses":{"200":{"description":"Budget raised","content":{"application/json":{"schema":{"type":"object","required":["campaign"],"properties":{"campaign":{"$ref":"#/components/schemas/CreatorCampaign"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"},"409":{"$ref":"#/components/responses/CreatorCampaignConflict"},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"}}}},"/v1/creator-campaigns/{campaignId}/activate":{"post":{"x-resource-group":"creator_campaigns","operationId":"activateCreatorCampaign","tags":["Creator Campaigns"],"summary":"Activate creator campaign","description":"Moves a `draft` or `paused` campaign to `active`, where creators can join and submit posts and\ntracked views accrue earnings. Needs at least one platform and a budget above zero; any other\nstarting state answers 409.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."}],"responses":{"200":{"description":"Campaign","content":{"application/json":{"schema":{"type":"object","required":["campaign"],"properties":{"campaign":{"$ref":"#/components/schemas/CreatorCampaign"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"},"409":{"$ref":"#/components/responses/CreatorCampaignConflict"}}}},"/v1/creator-campaigns/{campaignId}/pause":{"post":{"x-resource-group":"creator_campaigns","operationId":"pauseCreatorCampaign","tags":["Creator Campaigns"],"summary":"Pause creator campaign","description":"Moves an `active` campaign to `paused`: no new submissions, and approvals answer 409 until the\ncampaign is activated again.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."}],"responses":{"200":{"description":"Campaign","content":{"application/json":{"schema":{"type":"object","required":["campaign"],"properties":{"campaign":{"$ref":"#/components/schemas/CreatorCampaign"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"},"409":{"$ref":"#/components/responses/CreatorCampaignConflict"}}}},"/v1/creator-campaigns/{campaignId}/close":{"post":{"x-resource-group":"creator_campaigns","operationId":"closeCreatorCampaign","tags":["Creator Campaigns"],"summary":"Close creator campaign","description":"Closes an `active` or `paused` campaign for good and fires `creator_campaign.closed`. Open tracking windows are cancelled.\n\nA pool campaign is split among participants at this moment by their approved eligible views. Closing a pool campaign therefore answers 409 while any post still awaits review.\n\nA campaign also closes by itself once `endsAt` passed and every tracking window had its final read.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."}],"responses":{"200":{"description":"Campaign","content":{"application/json":{"schema":{"type":"object","required":["campaign"],"properties":{"campaign":{"$ref":"#/components/schemas/CreatorCampaign"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"},"409":{"$ref":"#/components/responses/CreatorCampaignConflict"}}}},"/v1/creator-campaigns/{campaignId}/participants":{"post":{"x-resource-group":"creator_campaigns","operationId":"createCampaignParticipant","tags":["Creator Campaigns"],"summary":"Invite campaign participant","description":"Invites one creator and returns their personal invite URL.\n\nSend the URL to the creator. On that page they connect their accounts (read-only), submit posts and see their earnings.\n\n### Invite rules\n\n- The URL is returned only here; inviting again creates no second link.\n- A creator is matched by email within your workspace, so the same person keeps one identity across your campaigns.\n\n### Errors\n\n- 409: the creator is already in the campaign, or the campaign is closed.\n- 403 `feature_not_available`: `caps.maxParticipants` is reached.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."},{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["displayName"],"properties":{"displayName":{"type":"string","minLength":1,"maxLength":200},"email":{"type":"string","format":"email"}}}}}},"responses":{"201":{"description":"Participant invited","content":{"application/json":{"schema":{"type":"object","required":["participant","inviteUrl"],"properties":{"participant":{"$ref":"#/components/schemas/CampaignParticipant"},"inviteUrl":{"type":"string","format":"uri","description":"The creator's personal join link. Treat it as a secret."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"},"409":{"$ref":"#/components/responses/CreatorCampaignConflict"},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"}}},"get":{"x-resource-group":"creator_campaigns","operationId":"listCampaignParticipants","tags":["Creator Campaigns"],"summary":"List campaign participants","description":"Lists the campaign's participants with their balances, flags and submission counts.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."},{"name":"status","in":"query","schema":{"type":"string","enum":["invited","active","suspended","removed"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"skip","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Participants","content":{"application/json":{"schema":{"type":"object","required":["participants","total"],"properties":{"participants":{"type":"array","items":{"$ref":"#/components/schemas/CampaignParticipant"}},"total":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"}}}},"/v1/creator-campaigns/{campaignId}/participants/{participantId}":{"get":{"x-resource-group":"creator_campaigns","operationId":"getCampaignParticipant","tags":["Creator Campaigns"],"summary":"Get campaign participant","description":"Returns one participant with connected accounts, balances by state, flags and submission counts.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."},{"name":"participantId","in":"path","required":true,"schema":{"type":"string"},"description":"Participant ID."}],"responses":{"200":{"description":"Participant","content":{"application/json":{"schema":{"type":"object","required":["participant"],"properties":{"participant":{"$ref":"#/components/schemas/CampaignParticipant"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"}}}},"/v1/creator-campaigns/{campaignId}/participants/{participantId}/suspend":{"post":{"x-resource-group":"creator_campaigns","operationId":"suspendCampaignParticipant","tags":["Creator Campaigns"],"summary":"Suspend campaign participant","description":"Suspends an `active` participant: they can no longer submit posts. Any other status answers 409.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."},{"name":"participantId","in":"path","required":true,"schema":{"type":"string"},"description":"Participant ID."}],"responses":{"200":{"description":"Participant suspended","content":{"application/json":{"schema":{"type":"object","required":["participant"],"properties":{"participant":{"$ref":"#/components/schemas/CampaignParticipant"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"},"409":{"$ref":"#/components/responses/CreatorCampaignConflict"}}}},"/v1/creator-campaigns/{campaignId}/participants/{participantId}/reinstate":{"post":{"x-resource-group":"creator_campaigns","operationId":"reinstateCampaignParticipant","tags":["Creator Campaigns"],"summary":"Reinstate campaign participant","description":"Reinstates a `suspended` participant: they can submit posts again. Any other status answers 409; a removed participant stays removed.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."},{"name":"participantId","in":"path","required":true,"schema":{"type":"string"},"description":"Participant ID."}],"responses":{"200":{"description":"Participant reinstated","content":{"application/json":{"schema":{"type":"object","required":["participant"],"properties":{"participant":{"$ref":"#/components/schemas/CampaignParticipant"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"},"409":{"$ref":"#/components/responses/CreatorCampaignConflict"}}}},"/v1/creator-campaigns/{campaignId}/participants/{participantId}/remove":{"post":{"x-resource-group":"creator_campaigns","operationId":"removeCampaignParticipant","tags":["Creator Campaigns"],"summary":"Remove campaign participant","description":"Removes the participant from the campaign. Their earnings stay in the ledger. Removing an\n`invited` participant revokes their invite: the link stops working. Removing an already\nremoved participant returns it unchanged.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."},{"name":"participantId","in":"path","required":true,"schema":{"type":"string"},"description":"Participant ID."}],"responses":{"200":{"description":"Participant removed","content":{"application/json":{"schema":{"type":"object","required":["participant"],"properties":{"participant":{"$ref":"#/components/schemas/CampaignParticipant"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"}}}},"/v1/creator-campaigns/{campaignId}/participants/{participantId}/move":{"post":{"x-resource-group":"creator_campaigns","operationId":"moveCampaignParticipant","tags":["Creator Campaigns"],"summary":"Move participant to another campaign","description":"Moves a creator invited or joined into the wrong campaign to another campaign of the same\nowner. The participant keeps its id, status and portal link, which now opens the target.\n\nPosts that fit the target (platform accepted, published after it started) move with it.\nUndecided posts that do not fit are rejected in this campaign with the reason; decided ones stay.\n\nAnswers 409 when the target is closed or full, the creator is already in it, the participant\nwas removed, or any money touched the participation (ledger entries, a payout batch or a\ntransfer). Money never moves between campaigns.\n\nFires `campaign_participant.removed` here and, for a creator who joined,\n`campaign_participant.joined` on the target.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign the participant is in now."},{"name":"participantId","in":"path","required":true,"schema":{"type":"string"},"description":"Participant ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["targetCampaignId"],"properties":{"targetCampaignId":{"type":"string","description":"Campaign to move the participant to. Same owner, not closed."}}}}}},"responses":{"200":{"description":"Participant moved","content":{"application/json":{"schema":{"type":"object","required":["participant","submissions"],"properties":{"participant":{"$ref":"#/components/schemas/CampaignParticipant"},"submissions":{"type":"object","required":["moved","rejected"],"properties":{"moved":{"type":"integer","description":"Posts that moved to the target."},"rejected":{"type":"integer","description":"Undecided posts rejected in this campaign because they did not fit the target."}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"},"409":{"$ref":"#/components/responses/CreatorCampaignConflict"}}}},"/v1/creator-campaigns/{campaignId}/participants/{participantId}/resend-invite":{"post":{"x-resource-group":"creator_campaigns","operationId":"resendCampaignParticipantInvite","tags":["Creator Campaigns"],"summary":"Resend campaign participant invite","description":"Emails an `invited` participant their personal invite link again. The link does not change,\nso a link you already sent keeps working. The email counts toward the daily invite email cap\nof your workspace.\n\nAnswers 409 when the participant has already joined, was suspended or removed, has no email,\nor the campaign is closed.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."},{"name":"participantId","in":"path","required":true,"schema":{"type":"string"},"description":"Participant ID."},{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"responses":{"200":{"description":"Invite email sent again","content":{"application/json":{"schema":{"type":"object","required":["participant"],"properties":{"participant":{"$ref":"#/components/schemas/CampaignParticipant"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"},"409":{"$ref":"#/components/responses/CreatorCampaignConflict"}}}},"/v1/creator-campaigns/{campaignId}/participants/{participantId}/settle":{"post":{"x-resource-group":"creator_campaigns","operationId":"settleCampaignParticipant","tags":["Creator Campaigns"],"summary":"Settle campaign participant","description":"Records a payout of the participant's payable balance and fires `campaign_payout.settled`.\n\nOmit `amountCents` to settle the whole payable balance. An amount above it answers 400, and nothing payable answers 409. Send an `Idempotency-Key` so a retry never records the payout twice.\n\n### Settlement modes\n\n- `none` settlement: records a payout you made elsewhere.\n- `external` settlement: pay from your own rails when `campaign_payout.payable` fires, then call this with your payout id in `externalReference` (required in this mode).\n- `treasury` settlement: transfers the amount from your Zernio balance to the creator's connected Stripe account, then records it with the Stripe transfer id as `externalReference`.\n\n### Treasury payouts\n\nThe transfer fee (4%, $0.50 minimum) is added on top: the creator receives the full amount and your balance is debited `totalCents`.\n\n- The creator must have finished payout setup from their campaign page (409 otherwise).\n- A balance that does not cover the amount plus the fee answers 402.\n- Money from a card top-up charged under 7 days ago cannot be paid out yet: a payout that needs it answers 409 `payout_funds_locked` with the day it can be sent.\n\nSet `recordOnly: true` to record a payout you made yourself instead of moving money through the treasury (the webhook then carries `recorded: true`).\n\nA treasury payout needs an owner, admin or billing admin, signed in or through a full-access key they created (403 otherwise). Recording with `recordOnly` does not.\n\n#### While Stripe confirms the transfer\n\nThe amount sits in the participant's `settling` balance; a reject in that window cannot reverse it.\n\n- If Stripe refuses the transfer, the amount returns to payable.\n- If Stripe does not answer, the amount stays in `settling`. The next settle call for this participant finishes that payout first (even with nothing payable left).\n\n#### Conflicts (409)\n\n- A retry asking for a different `amountCents` than the payout in progress answers 409 with the amount in progress.\n- A settle while another request is still waiting on Stripe for the same payout answers 409 (\"This payout is being sent to Stripe right now. Try again in a minute.\").\n- A payout Stripe has not confirmed after 24 hours answers 409 (\"This payout is being confirmed with Stripe. Try again after the next reconciliation (within 24 hours).\") until the daily reconciliation finishes it: settled if Stripe made the transfer, returned to payable if it did not.\n- A creator held by an unfinished payout batch answers 409 (\"This creator is in a card payout that is not finished yet.\").\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."},{"name":"participantId","in":"path","required":true,"schema":{"type":"string"},"description":"Participant ID."},{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amountCents":{"type":"integer","minimum":1,"description":"Defaults to the whole payable balance."},"externalReference":{"type":"string","minLength":1,"maxLength":200,"description":"Your payout id. Required when the campaign settles externally."},"recordOnly":{"type":"boolean","description":"Treasury campaigns only: record a payout you already made outside Zernio, without moving money. Ignored on other settlement modes, which always record."}}}}}},"responses":{"201":{"description":"Settlement recorded","content":{"application/json":{"schema":{"type":"object","required":["settlement"],"properties":{"settlement":{"$ref":"#/components/schemas/CampaignSettlement"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"x-summary":"Your balance does not cover the amount plus fee: top up and retry the settlement.","description":"Your Zernio balance does not cover the amount plus the fee on top (code `payment_required`). Top up and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"},"409":{"$ref":"#/components/responses/CreatorCampaignConflict"},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"},"502":{"x-summary":"Stripe did not confirm the transfer: retry the settle call, which does not transfer twice within the idempotency window.","description":"Stripe did not confirm the transfer (code `temporarily_unavailable`). Retry the settle call: the transfer is not made twice within Stripe's 24-hour idempotency window; after that, retries answer 409 until the daily reconciliation settles the payout or returns it to payable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/creator-campaigns/{campaignId}/payout-batches":{"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."}],"post":{"x-resource-group":"creator_campaigns","operationId":"createCampaignPayoutBatch","tags":["Creator Campaigns"],"summary":"Pay creators with one card payment","description":"Pays exactly what is owed to the creators of a `treasury` campaign by charging the billing owner's saved card, with no redirect.\n\n### How it works\n\n1. Every payable creator who finished payout setup (or only `participantIds`, minus `excludeParticipantIds`) is held in `settling`.\n2. The saved card (the default one, or `paymentMethodId`) is charged the total plus the fee (4% per creator, 50 cent minimum) while the payer is present.\n3. Once the charge succeeds, each creator gets a transfer funded by it, and the batch ends `paid` or `partially_failed`.\n\nA creator whose payouts were disabled before the payment landed is skipped and stays payable.\n\n### 3D Secure\n\n`payment.status: requires_action` means the bank asked the payer to confirm. Complete it with Stripe.js `handleNextAction({ clientSecret })`, then call `POST /v1/payout-batches/{batchId}/confirm`.\n\nOne left unfinished is cancelled after 30 minutes and every amount is payable again. Cancel it sooner with `POST /v1/payout-batches/{batchId}/cancel`.\n\n### Limits and errors\n\n- 402 `payment_required`: no saved card. Nothing is held.\n- 402 `card_declined`: the bank's reason; every amount is payable again.\n- 402: card payouts are limited to $10,000.00 gross per rolling 30 days by default. Over it the call answers \"Over your instant payout limit. Top up your balance to pay more this month, or contact support to raise the limit.\"\n- 400: nothing payable (\"Nothing is payable.\").\n\n### Access and retries\n\nNeeds an owner, admin or billing admin, signed in or through a full-access key they created.\n\nSend an `Idempotency-Key` so a retry never opens a second batch.\n","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"participantIds":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":500,"description":"Pay only these participants. Defaults to every payable participant who is ready."},"excludeParticipantIds":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":500,"description":"Leave these participants out."},"paymentMethodId":{"type":"string","description":"A saved card of the billing owner's (`pm_...`). Defaults to the default payment method."}}}}}},"responses":{"201":{"description":"Batch created and the card charged, or the bank asked for 3D Secure.","content":{"application/json":{"schema":{"type":"object","required":["batch","payment"],"properties":{"batch":{"$ref":"#/components/schemas/PayoutBatch"},"payment":{"type":"object","required":["status","clientSecret"],"properties":{"status":{"type":"string","enum":["succeeded","processing","requires_action"]},"clientSecret":{"type":["string","null"],"description":"PaymentIntent client secret for Stripe.js handleNextAction; set only when status is requires_action"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Over the instant payout limit or no saved card (code `payment_required`), or the bank declined the charge (code `card_declined`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/MoneyForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"},"409":{"$ref":"#/components/responses/CreatorCampaignConflict"}}},"get":{"x-resource-group":"creator_campaigns","operationId":"listCampaignPayoutBatches","tags":["Creator Campaigns"],"summary":"List payout batches","description":"The campaign's payout batches, newest first, with each creator's item.","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"skip","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Payout batches.","content":{"application/json":{"schema":{"type":"object","required":["batches","total"],"properties":{"batches":{"type":"array","items":{"$ref":"#/components/schemas/PayoutBatch"}},"total":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"}}}},"/v1/creator-campaigns/{campaignId}/invite-link":{"post":{"x-resource-group":"creator_campaigns","operationId":"createCampaignInviteLink","tags":["Creator Campaigns"],"summary":"Create campaign invite link","description":"Creates the campaign's open invite link: anyone with it can join as a participant (up to\n`caps.maxParticipants`). Creating a new link revokes the previous one. The URL is returned only\nhere. Answers 409 on a closed campaign.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."}],"responses":{"201":{"description":"Invite link created","content":{"application/json":{"schema":{"type":"object","required":["inviteUrl"],"properties":{"inviteUrl":{"type":"string","format":"uri"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"},"409":{"$ref":"#/components/responses/CreatorCampaignConflict"}}}},"/v1/creator-campaigns/{campaignId}/submissions":{"get":{"x-resource-group":"creator_campaigns","operationId":"listCampaignSubmissions","tags":["Creator Campaigns"],"summary":"List campaign submissions","description":"Lists submitted posts with views, earnings, authenticity score and flags. Filter by status,\nparticipant, flag, platform or score range to build a review queue, for example\n`status=pending_review`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."},{"name":"status","in":"query","schema":{"type":"string","enum":["received","tracking","pending_review","approved","rejected","expired","withdrawn"]}},{"name":"participantId","in":"query","schema":{"type":"string"}},{"name":"flag","in":"query","schema":{"type":"string","enum":["duplicate_media","duplicate_post","view_spike","linked_accounts","cross_operator","unreachable","post_deleted","account_restricted","low_authenticity","x_read_cap","paid_views","organic_unverified"]}},{"name":"platform","in":"query","schema":{"type":"string","enum":["tiktok","instagram","youtube","threads","pinterest","facebook","twitter"]}},{"name":"minScore","in":"query","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"maxScore","in":"query","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"q","in":"query","schema":{"type":"string","minLength":1,"maxLength":100},"description":"Only submissions whose creator name or post link contains this text, ignoring case."},{"name":"sort","in":"query","schema":{"type":"string","enum":["submittedAt","viewsEligible","engagementsLatest","earnedCents","authenticityScore"],"default":"submittedAt"},"description":"What to sort by. Posts with no value to sort by (not read yet, not scored) come last in either direction."},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"skip","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Submissions","content":{"application/json":{"schema":{"type":"object","required":["submissions","total"],"properties":{"submissions":{"type":"array","items":{"$ref":"#/components/schemas/CampaignSubmission"}},"total":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"}}}},"/v1/creator-campaigns/{campaignId}/submissions/{submissionId}":{"get":{"x-resource-group":"creator_campaigns","operationId":"getCampaignSubmission","tags":["Creator Campaigns"],"summary":"Get campaign submission","description":"Returns one submission with its per-sync samples (views, likes, comments, shares, saves).\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."},{"name":"submissionId","in":"path","required":true,"schema":{"type":"string"},"description":"Submission ID."}],"responses":{"200":{"description":"Submission","content":{"application/json":{"schema":{"type":"object","required":["submission"],"properties":{"submission":{"$ref":"#/components/schemas/CampaignSubmissionDetail"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"}}}},"/v1/creator-campaigns/{campaignId}/submissions/{submissionId}/approve":{"post":{"x-resource-group":"creator_campaigns","operationId":"approveCampaignSubmission","tags":["Creator Campaigns"],"summary":"Approve campaign submission","description":"Approves a `tracking` or `pending_review` submission of an active campaign and fires `campaign_submission.approved`.\n\nThe Zernio dashboard offers Approve only on `pending_review` (a post that needs a decision) and waits for `tracking` posts to get there. The API accepts `tracking` so an integration can approve early.\n\n### Earnings\n\n- What the post earned so far moves to owed and is held for the campaign's `holdDays`.\n- Later earnings post straight to owed.\n- A per-post campaign pays `perApprovedPostCents` here.\n\n### Errors\n\n- 409: the submission is in any other state.\n- 409 (`invalid_resource_state`, \"This post is already approved in another campaign of yours.\"): the same post was approved in another of your campaigns, so one post never earns twice.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."},{"name":"submissionId","in":"path","required":true,"schema":{"type":"string"},"description":"Submission ID."},{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"responses":{"200":{"description":"Submission approved","content":{"application/json":{"schema":{"type":"object","required":["submission"],"properties":{"submission":{"$ref":"#/components/schemas/CampaignSubmission"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"},"409":{"x-summary":"The campaign or submission cannot be approved now, or the post is approved elsewhere: check its state before retrying.","description":"The campaign or submission is not in a state that allows approval, or the same post is already approved in another of your campaigns (`invalid_resource_state`, \"This post is already approved in another campaign of yours.\"). Also returned while the same `Idempotency-Key` is still processing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"}}}},"/v1/creator-campaigns/{campaignId}/submissions/{submissionId}/reject":{"post":{"x-resource-group":"creator_campaigns","operationId":"rejectCampaignSubmission","tags":["Creator Campaigns"],"summary":"Reject campaign submission","description":"Rejects a submission (also one already approved) and fires `campaign_submission.rejected`. Its\ntracking window is cancelled and its unsettled earnings return to the campaign budget.\nRejecting a rejected submission returns it unchanged; an expired or withdrawn one answers 409.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."},{"name":"submissionId","in":"path","required":true,"schema":{"type":"string"},"description":"Submission ID."},{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","minLength":1,"maxLength":1000}}}}}},"responses":{"200":{"description":"Submission rejected","content":{"application/json":{"schema":{"type":"object","required":["submission"],"properties":{"submission":{"$ref":"#/components/schemas/CampaignSubmission"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"},"409":{"$ref":"#/components/responses/CreatorCampaignConflict"},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"}}}},"/v1/creator-campaigns/{campaignId}/submissions/{submissionId}/reopen":{"post":{"x-resource-group":"creator_campaigns","operationId":"reopenCampaignSubmission","tags":["Creator Campaigns"],"summary":"Reopen campaign submission","description":"Puts a rejected submission back to `pending_review` so it can be decided again. No webhook fires.\n\nIts tracking window resumes, so it works only while that window has not ended.\n\n### When it can't be reopened\n\n- The tracking window has ended: 409 `invalid_resource_state` (\"This post's tracking window has ended.\").\n- A post that earned money which was already paid out cannot be reopened.\n- A post of a closed campaign cannot be reopened.\n- Any status other than rejected or `pending_review` answers 409.\n\nReopening a submission that is already `pending_review` returns it unchanged.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."},{"name":"submissionId","in":"path","required":true,"schema":{"type":"string"},"description":"Submission ID."},{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"responses":{"200":{"description":"Submission reopened","content":{"application/json":{"schema":{"type":"object","required":["submission"],"properties":{"submission":{"$ref":"#/components/schemas/CampaignSubmission"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"},"409":{"$ref":"#/components/responses/CreatorCampaignConflict"},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"}}}},"/v1/creator-campaigns/{campaignId}/payables":{"get":{"x-resource-group":"creator_campaigns","operationId":"listCampaignPayables","tags":["Creator Campaigns"],"summary":"List campaign payables","description":"Lists every participant with a payable balance (earnings past their hold), with the ledger\nentries behind it. Pay these, then record each payout with the settle endpoint.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."}],"responses":{"200":{"description":"Payables","content":{"application/json":{"schema":{"type":"object","required":["payables"],"properties":{"payables":{"type":"array","items":{"$ref":"#/components/schemas/CampaignPayable"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"}}}},"/v1/creator-campaigns/{campaignId}/adjustments":{"post":{"x-resource-group":"creator_campaigns","operationId":"createCampaignAdjustment","tags":["Creator Campaigns"],"summary":"Create campaign adjustment","description":"Posts a manual adjustment to a participant's payable balance against the campaign budget: a\npositive amount credits the participant (a bonus), a negative one claws back. `cause` is kept\non the ledger entry. A claw-back larger than the payable balance answers 409.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."},{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["participantId","amountCents","cause"],"properties":{"participantId":{"type":"string"},"amountCents":{"type":"integer","description":"Non-zero. Positive credits, negative claws back."},"cause":{"type":"string","minLength":1,"maxLength":500}}}}}},"responses":{"201":{"description":"Adjustment posted","content":{"application/json":{"schema":{"type":"object","required":["entry"],"properties":{"entry":{"$ref":"#/components/schemas/CampaignAdjustment"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"},"409":{"$ref":"#/components/responses/CreatorCampaignConflict"},"422":{"$ref":"#/components/responses/IdempotencyKeyReused"}}}},"/v1/creator-campaigns/{campaignId}/ledger":{"get":{"x-resource-group":"creator_campaigns","operationId":"listCampaignLedger","tags":["Creator Campaigns"],"summary":"List campaign ledger","description":"Lists ledger entries, newest first.\n\nWithout `participantId` it lists every entry of the campaign:\n\n- earnings drawn from the budget (accruals, per-post payments, pool shares, adjustments)\n- the approvals, hold releases and settlements that move money between its participants' buckets\n- their reversals\n\nPass `participantId` to narrow the list to one participant's entries.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."},{"name":"participantId","in":"query","schema":{"type":"string"},"description":"List only this participant's entries."},{"name":"kind","in":"query","schema":{"type":"string","enum":["accrual","approval","hold_release","adjustment","settling","settlement","reversal","topup","transfer","fee","usage","grant"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"skip","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Ledger entries","content":{"application/json":{"schema":{"type":"object","required":["entries","pagination"],"properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/CampaignLedgerEntry"}},"pagination":{"type":"object","required":["total","limit","skip"],"properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"skip":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"}}}},"/v1/creator-campaigns/{campaignId}/report":{"get":{"x-resource-group":"creator_campaigns","operationId":"getCampaignReport","tags":["Creator Campaigns"],"summary":"Get campaign report","description":"Returns spend against budget, views, submission counts, the top ten participants by earnings\nand the authenticity score distribution.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign ID."}],"responses":{"200":{"description":"Campaign report","content":{"application/json":{"schema":{"type":"object","required":["report"],"properties":{"report":{"$ref":"#/components/schemas/CampaignReport"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/CreatorCampaignForbidden"},"404":{"$ref":"#/components/responses/CreatorCampaignNotFound"}}}}}}